|
| 1 | +# Contributing |
| 2 | + |
| 3 | +We welcome and encoruage everyone to contribute to GemPy! |
| 4 | +Contributions can be questions, bug reports, feature requests and new code. |
| 5 | +Here is how to get started. |
| 6 | + |
| 7 | +## Issues |
| 8 | + |
| 9 | +### Questions |
| 10 | + |
| 11 | +For questions about GemPy (e.g. its applications, functionality, and usage), |
| 12 | +please [search the existing issues for related questions](https://github.com/cgre-aachen/gempy/issues). |
| 13 | +If your question has not already been asked, then [make a new issue](https://github.com/cgre-aachen/gempy/issues/new/choose). |
| 14 | + |
| 15 | +### Reporting Bugs |
| 16 | + |
| 17 | +Please report bugs on the [issue page using the bug report template](https://github.com/cgre-aachen/gempy/issues/new?assignees=&labels=&template=bug_report.md&title=) and label the issue as a bug. |
| 18 | +The template asks essential questions for you to answer so that we can to understand, reproduce, and fix the bug. |
| 19 | +Be verbose! |
| 20 | +Whenever possible, provide tracebacks and/or error messages, screenshots, and sample code or other files. |
| 21 | + |
| 22 | +### Feature Requests |
| 23 | + |
| 24 | +We encourage users to submit ideas for improvements to the GemPy project. For |
| 25 | +this please create an issue on the |
| 26 | + [issue page](https://github.com/cgre-aachen/gempy/issues) with the *Feature |
| 27 | + Request* template and label. Please make sure to use a descriptive title and to |
| 28 | + provide ample background information to help us implement that functionality |
| 29 | + in the future. |
| 30 | + |
| 31 | +## Contributing New Code |
| 32 | + |
| 33 | +Any code contributions are welcome, |
| 34 | +whether fixing a typo or bug, |
| 35 | +adding new post-processing/plotting functionality, |
| 36 | +improve core functionality, |
| 37 | +or anything that you think should be in the repository. |
| 38 | + |
| 39 | +Contributions should address an open issue (either a bug or a feature request). |
| 40 | +If you have found a new bug |
| 41 | +or have an idea or a new feature, |
| 42 | +then please [open the issue](https://github.com/cgre-aachen/gempy/issues/new/choose) |
| 43 | +for discussion and link to that issue in your pull request. |
| 44 | + |
| 45 | +### Python code guidelines |
| 46 | +We aim to follow particular Python coding guidelines to improve the sustainability and positive impact of this community project: |
| 47 | + |
| 48 | +- Follow [The Zen of Python](https://www.python.org/dev/peps/pep-0020/), most importantly "readability counts" when writing Python code. |
| 49 | +- Adhere to the [Style Guide for Python Code (PEP8)](https://www.python.org/dev/peps/pep-0008/). |
| 50 | +- Write thorough and effective documentation: |
| 51 | +Make a docstring for each module, function, class, and method, |
| 52 | +all following [PEP 257](https://www.python.org/dev/peps/pep-0257/) for high-level guidelines |
| 53 | +and [Google Python Style Guidelines](http://google.github.io/styleguide/pyguide.html) for Syntax. |
| 54 | +**Example function documentation:** |
| 55 | +```python |
| 56 | +def func(arg1: int, arg2: float) -> int: |
| 57 | + """A concise one line summary of the function. |
| 58 | + |
| 59 | + Additional information and description of the function, if necessary. This |
| 60 | + can be as long and verbose as you think is necessary for other users and |
| 61 | + developers to understand your functionality. |
| 62 | + |
| 63 | + Args: |
| 64 | + arg1 (int): Description of the first argument. |
| 65 | + arg2 (float): Description of the second argument. Please use hanging |
| 66 | + indentation for multi-line argument descriptions. |
| 67 | + |
| 68 | + Returns: |
| 69 | + (int) Description of the return value(s) |
| 70 | + """ |
| 71 | + return 42 |
| 72 | +``` |
| 73 | +- The code should explain the *what* and *how*. Add inline comments to explain the *why*. |
| 74 | +If an inline comment seems to be needed, consider first making the code more readable. |
| 75 | +For all comments, follow [PEP 8](https://www.python.org/dev/peps/pep-0008/). |
| 76 | +- Test every line of code. Untested code is dead code. |
| 77 | + |
| 78 | +### Licensing |
| 79 | + |
| 80 | +All contributed code will be licensed under |
| 81 | +[a LGPL-3 license](https://github.com/cgre-aachen/gempy/blob/master/LICENSE). |
| 82 | +If you did not write the code yourself, |
| 83 | +it is your responsibility to ensure that the existing license is compatible |
| 84 | +and included in the contributed files. |
| 85 | +In general we discourage contributing third party code. |
| 86 | + |
| 87 | +### Testing |
| 88 | + |
| 89 | +Our test suite uses [`pytest`](https://docs.pytest.org/). |
| 90 | +You should be familiar with `pytest` before contributing. |
| 91 | +Please run all tests locally before creating a pull request. |
| 92 | +You can do this by running `pytest` via your terminal in your GemPy folder: |
| 93 | +```bash |
| 94 | +cd ./path/to/gempy |
| 95 | +pytest |
| 96 | +``` |
| 97 | +All tests are located in the `test` folder and its subfolders. |
| 98 | +All contributed code must include test code in the pull request. |
| 99 | + |
| 100 | +### Pull Requests |
| 101 | + |
| 102 | +All contributions are made via pull requests (PR's) to the master branch. |
| 103 | +You must complete the checklist in the [PR template](https://github.com/cgre-aachen/gempy/blob/master/.github/PULL_REQUEST_TEMPLATE.md) before we will review the PR and consider merging your contribution. |
0 commit comments