|
| 1 | +# Contributing |
| 2 | + |
| 3 | +👍🎉 Thank you for taking the time to contribute! 🎉👍 |
| 4 | + |
| 5 | +In this file you will find all the steps necessary to guide you through your first contribution to the project. |
| 6 | + |
| 7 | +Please note our [Code of Conduct](https://github.com/gnikit/fortls/blob/master/CODE_OF_CONDUCT.md) and adhere to it in all your interactions with this project. |
| 8 | + |
| 9 | +## 📚 Getting Started |
| 10 | + |
| 11 | +A good place to start is the [Issues tab](https://github.com/gnikit/fortls/issues) on GitHub. Look for any issues with the `help wanted` tag. |
| 12 | + |
| 13 | +### Downloading ⬇️ |
| 14 | + |
| 15 | +Firstly, fork the repository from <https://github.com/gnikit/fortls>. |
| 16 | + |
| 17 | +Then clone the forked repository into your local machine. |
| 18 | + |
| 19 | +```sh |
| 20 | +[email protected]: <YOUR-USERNAME >/fortls.git |
| 21 | +``` |
| 22 | + |
| 23 | +Where `<YOUR-USERNAME>` should be your GitHub username. |
| 24 | + |
| 25 | +### Dependencies |
| 26 | + |
| 27 | +To build this project you will need [Python](https://www.python.org/) `>= 3.7` and [pip](https://www.python.org/) `>= 21.0`. |
| 28 | +To install all Python dependencies open a terminal go into the `fortls` cloned folder and run: |
| 29 | + |
| 30 | +```sh |
| 31 | +pip install .[dev,docs] |
| 32 | +``` |
| 33 | + |
| 34 | +### Testing 🧪 |
| 35 | + |
| 36 | +To verify that your cloning of the GitHub repository work as expected open a terminal and run: |
| 37 | + |
| 38 | +```sh |
| 39 | +pytest -v |
| 40 | +``` |
| 41 | +This will run the entire unit test suite. You can also run this to verify that you haven't broken anything in the code. |
| 42 | + |
| 43 | +👉 **Tip!** You can run individual tests by selecting the path to the Python file and the method |
| 44 | +```sh |
| 45 | +pytest test/test_interface.py::test_version_update_pypi |
| 46 | +``` |
| 47 | + |
| 48 | +### Developing & Debugging 🐞️ |
| 49 | + |
| 50 | +You can now start writing code! Your local `fortls` version will be updated with every code change you make, so you can use your normal code editor to checkout the `fortls` features that you have implemented. |
| 51 | +It is however considerably easier to create compact unittests to check if your changes have worked. |
| 52 | + |
| 53 | +A `fortls` test normally involves writing a Python function which sends a JSONRPC request to the server and then test checks for the correct server response. |
| 54 | +Often times small bits of Fortran source code also have to be submited to be used by the test. |
| 55 | +You can find varisous test examples in the `tests` directory. |
| 56 | + |
| 57 | + |
| 58 | +👉 **Tip!** You can attach a debugger to the main `fortls` source code during unittesting which should allow you to pause, break, step into, etc. while testing, thus making it easier to find mistakes. |
| 59 | + |
| 60 | + |
| 61 | +### Merging |
| 62 | + |
| 63 | +To merge your changes to the main `fortls` repository push your branch on GitHub and open a [Pull Request](https://github.com/gnikit/fortls/pulls). Ping `@gnikit` to review your PR. |
0 commit comments