|
| 1 | +# Contributing to Pydra |
| 2 | + |
| 3 | +Welcome to the Pydra repository! We're excited you're here and want to contribute. |
| 4 | + |
| 5 | +These guidelines are designed to make it as easy as possible to get involved. |
| 6 | +If you have any questions that aren't discussed below, please let us know by opening an [issue][link_doc_issues]! |
| 7 | + |
| 8 | +Before you start you'll need to set up a free GitHub account and sign in, here are some [instructions][link_signupinstructions]. |
| 9 | +If you are not familiar with version control systems such as git, |
| 10 | + introductions and tutorials may be found [here](http://www.reproducibleimaging.org/module-reproducible-basics/02-vcs/). |
| 11 | + |
| 12 | + |
| 13 | +## How can you contribute |
| 14 | + |
| 15 | +There are two main ways of contributing to the project: |
| 16 | + |
| 17 | +**1. Provide suggestions, comments and report problems** |
| 18 | + |
| 19 | +If you want to share anything with the community and developers, please open [a new issue][link_new_issues]. |
| 20 | +There are multiple templates that you can choose from, please fill them out to the best of your ability. |
| 21 | +- **Bug report** - report if something is not working correctly or the documentation is incorrect |
| 22 | +- **Documentation improvement** - request improvements to the documentation and tutorials |
| 23 | +- **Feature request** - share an idea for a new feature, or changes to an existing feature |
| 24 | +- **Maintenance and Delivery** - suggest changes to development infrastructure, testing, and delivery |
| 25 | +- **Questions** - ask questions regarding the tool and the usage |
| 26 | + |
| 27 | + |
| 28 | +**2. Improve the code and documentation** |
| 29 | +We appreciate all improvement to the Pydra code or documentation. |
| 30 | +Please try to follow the recommended steps, and don't hesitate to ask questions! |
| 31 | + |
| 32 | + |
| 33 | +**i. Comment on an existing issue or open a new issue describing your idea** |
| 34 | + |
| 35 | +This allows other members of the Pydra development team to confirm |
| 36 | +that you aren't overlapping with work that's currently underway and |
| 37 | +that everyone is on the same page with the goal of the work you're going to carry out. |
| 38 | + |
| 39 | +**ii. [Fork][link_fork] the [Pydra repository][link_pydra] to your profile** |
| 40 | + |
| 41 | +This is now your own unique copy of the Pydra repository. |
| 42 | +Changes here won't affect anyone else's work, so it's a safe space to explore edits to the code! |
| 43 | + |
| 44 | +**iii. [Clone][link_clone] the repository to your local machine** |
| 45 | + |
| 46 | +You can clone your Pydra repository (from your fork!) in order to create a local copy of the code on your machine. |
| 47 | + |
| 48 | +(Make sure to keep your fork up to date with the original Pydra repository. |
| 49 | +One way to do this is to [configure a new remote named "upstream"](https://help.github.com/articles/configuring-a-remote-for-a-fork/) |
| 50 | + and to [sync your fork with the upstream repository][link_updateupstreamwiki].) |
| 51 | + |
| 52 | + |
| 53 | +**iv. Install Pydra on your machine** |
| 54 | + |
| 55 | +To install your version of Pydra, and the dependencies needed for development, |
| 56 | +in your Python environment (Python 3.7 or higher), run `pip install -e ".[dev]"` |
| 57 | +from your local Pydra directory. |
| 58 | + |
| 59 | +In order to check if everything is working correctly, run the tests |
| 60 | +using [pytest](https://docs.pytest.org/en/latest/), e.g. `pytest -vs pydra` |
| 61 | + |
| 62 | +**v. Install pre-commit.** |
| 63 | + |
| 64 | +[pre-commit](https://pre-commit.com/) is a git hook for running operations at commit time. To use it in |
| 65 | +your environment, do `pip install pre-commit` following by `pre-commit install` |
| 66 | +inside your source directory. |
| 67 | + |
| 68 | + |
| 69 | +**vi. Make the changes you've discussed.** |
| 70 | + |
| 71 | +It's a good practice to create [a new branch](https://help.github.com/articles/about-branches/) |
| 72 | +of the repository for a new set of changes. |
| 73 | +Once you start working on your changes, test frequently to ensure you are not breaking the existing code. |
| 74 | +It's also a good idea to [commit][link_commit] your changes whenever |
| 75 | +you finish specific task, and [push][link_push] your work to your GitHub repository. |
| 76 | + |
| 77 | + |
| 78 | +**vii. Submit a [pull request][link_pullrequest].** |
| 79 | + |
| 80 | +A new pull request for your changes should be created from your fork of the repository |
| 81 | +after you push all the changes you made on your local machine. |
| 82 | + |
| 83 | +When opening a pull request, please use one of the following prefixes: |
| 84 | + |
| 85 | + |
| 86 | +* **[ENH]** for enhancements |
| 87 | +* **[FIX]** for bug fixes |
| 88 | +* **[MNT]** for maintenance |
| 89 | +* **[TST]** for new or updated tests |
| 90 | +* **[DOC]** for new or updated documentation |
| 91 | +* **[STY]** for stylistic changes |
| 92 | +* **[REF]** for refactoring existing code |
| 93 | + |
| 94 | + |
| 95 | + |
| 96 | +**Pull requests should be submitted early and often (please don't mix too many unrelated changes within one PR)!** |
| 97 | +If your pull request is not yet ready to be merged, please also include the **[WIP]** prefix (you can remove it once your PR is ready to be merged). |
| 98 | +This tells the development team that your pull request is a "work-in-progress", and that you plan to continue working on it. |
| 99 | + |
| 100 | +Review and discussion on new code can begin well before the work is complete, and the more discussion the better! |
| 101 | +The development team may prefer a different path than you've outlined, so it's better to discuss it and get approval at the early stage of your work. |
| 102 | + |
| 103 | +One your PR is ready a member of the development team will review your changes to confirm that they can be merged into the main codebase. |
| 104 | + |
| 105 | +## Notes for New Code |
| 106 | + |
| 107 | +#### Catching exceptions |
| 108 | +In general, do not catch exceptions without good reason. |
| 109 | +For non-fatal exceptions, log the exception as a warning and add more information about what may have caused the error. |
| 110 | + |
| 111 | +If you do need to catch an exception, raise a new exception using ``raise NewException("message") from oldException)``. |
| 112 | +Do not log this, as it creates redundant/confusing logs. |
| 113 | + |
| 114 | +#### Testing |
| 115 | +Testing is a crucial step of code development, remember: |
| 116 | +- new code should be tested |
| 117 | +- bug fixes should include an example that exposes the issue |
| 118 | +- any new features should have tests that show at least a minimal example. |
| 119 | + |
| 120 | +If you're not sure what this means for your code, please ask in your pull request, |
| 121 | +we will help you with writing the tests. |
| 122 | + |
| 123 | +## Recognizing contributions |
| 124 | + |
| 125 | +We welcome and recognize all contributions from documentation to testing to code development. |
| 126 | + |
| 127 | +The development team member who accepts/merges your pull request will update the CHANGES file to reference your contribution. |
| 128 | + |
| 129 | +You can see a list of current contributors in our [zenodo file][link_zenodo]. |
| 130 | +If you are new to the project, don't forget to add your name and affiliation there! |
| 131 | + |
| 132 | + |
| 133 | +[link_pydra]: https://github.com/nipype/pydra |
| 134 | +[link_signupinstructions]: https://help.github.com/articles/signing-up-for-a-new-github-account |
| 135 | +[link_new_issues]: https://github.com/nipype/pydra/issues/new/choose |
| 136 | +[link_doc_issues]: https://github.com/nipype/pydra/issues/new?assignees=&labels=documentation&template=documentation.md&title= |
| 137 | + |
| 138 | +[link_pullrequest]: https://help.github.com/articles/creating-a-pull-request-from-a-fork/ |
| 139 | +[link_fork]: https://help.github.com/articles/fork-a-repo/ |
| 140 | +[link_clone]: https://help.github.com/articles/cloning-a-repository/ |
| 141 | +[link_updateupstreamwiki]: https://help.github.com/articles/syncing-a-fork/ |
| 142 | +[link_push]: https://help.github.com/en/github/using-git/pushing-commits-to-a-remote-repository |
| 143 | +[link_commit]: https://git-scm.com/docs/git-commit |
| 144 | + |
| 145 | +[link_zenodo]: https://github.com/nipype/pydra/blob/master/.zenodo.json |
0 commit comments