-
Notifications
You must be signed in to change notification settings - Fork 12
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #58 from m-miedema/DOC/CGuide
Migrating existing Contributor Guide to wiki-style format
- Loading branch information
Showing
19 changed files
with
583 additions
and
1,147 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| ## Contribution workflow | ||
|
|
||
| There are many descriptions of a good contribution workflow out there. | ||
| For instance, we suggest to have a look at [tedana's workflow](https://github.com/ME-ICA/tedana/blob/master/CONTRIBUTING.md#making-a-change). | ||
| At `physiopy`, we follow a very similar workflow. The only three | ||
| differences are: | ||
|
|
||
| - If you see an open issue that you would like to work on, check if it | ||
| is assigned. If it is, ask the assignee if they need help or want to | ||
| be substituted before starting to work on it. | ||
| - We ask you to test the code locally before merging it, and then, if | ||
| possible, write some automatic tests for the code to be run in our | ||
| Continuous Integration! Check the testing section below to know | ||
| more. | ||
| - We suggest opening a draft PR as soon as you can - so it's easier | ||
| for us to help you! | ||
|
|
||
| You can find more in-detail description of this process in the following sections of the guide. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,115 @@ | ||
| ## Labels | ||
|
|
||
| The current list of labels are | ||
| [here](https://github.com/physiopy/phys2bids/labels). They can be used | ||
| for **Issues**, **PRs**, or both. We use | ||
| [auto](https://github.com/intuit/auto) to automate our semantic | ||
| versioning and Pypi upload, so **it's extremely important to use the | ||
| right PR labels**! | ||
|
|
||
| ### Issue & PR labels | ||
|
|
||
| -  Improvements or additions to documentation. This | ||
| category includes (but is not limited to) docs pages, docstrings, | ||
| and code comments. | ||
|
|
||
| -  Whatever this is, it exists already! Maybe it's a closed | ||
| Issue/PR, that should be reopened. | ||
|
|
||
| -  New features added or requested. This normally goes with a `minormod` label for PRs. | ||
|
|
||
| -  As part of the scientific community, we care about outreach. Check the relevant section about it, but know that this | ||
| Issue/PR contains information or tasks about abstracts, talks, | ||
| demonstrations, papers. | ||
|
|
||
| -  Issue or PR should not be worked on until the resolution of other issues or PRs. | ||
|
|
||
| -  This Issue or PR has been released. | ||
|
|
||
| -  This is for testing features, writing tests or producing testing code. Both user testing and CI testing! | ||
|
|
||
| -  If you don't know where to start, start here! This is probably related to a milestone due soon! | ||
|
|
||
| ### Issue-only labels | ||
|
|
||
| -  This issue is suggested for BrainHack participants! | ||
|
|
||
| -  Something isn't working. It either breaks the code or has an | ||
| unexpected outcome. | ||
|
|
||
| -  This issue contains information about the `physiopy` | ||
| community (e.g. the next developer call) | ||
|
|
||
| -  Discussion of a concept or implementation. These Issues | ||
| are prone to be open ad infinitum. Jump in the conversation if you | ||
| want! | ||
|
|
||
| -  Good for newcomers. These issues calls for a | ||
| **fairly** easy enhancement, or for a change that helps/requires | ||
| getting to know the code better. They have educational value, and | ||
| for this reason, unless urgent, experts in the topic should refrain | ||
| from closing them - but help newcomers closing them. | ||
|
|
||
| -  Dedicated to the hacktoberfest event, so that people | ||
| can help and feel good about it (and show it with a T-shirt!). | ||
| **Such commits will not be recognised in the all-contributor table, | ||
| unless otherwise specified**. | ||
|
|
||
| -  Extra attention is needed here! It's a good place to have a look! | ||
|
|
||
| -  Improve nonfunctional attributes. Which means rewriting | ||
| the code or the documentation to improve performance or just because | ||
| there's a better way to express those lines. It might create a | ||
| `majormod` PR. | ||
|
|
||
| -  Further information is requested, from users to | ||
| developers. Try to respond to this! | ||
|
|
||
| -  This will not be worked on, until further notice. | ||
|
|
||
| ### PR-only labels | ||
|
|
||
| #### Labels for semantic release and changelogs | ||
|
|
||
| -  These PRs close an issue labelled `Bug`. They also increase | ||
| the semantic versioning for fixes (+0.0.1). | ||
|
|
||
| -  Pull requests that update a dependency file | ||
|
|
||
| -  See above. This PR won't trigger a release, but it will be reported in the changelog. | ||
|
|
||
| -  These PRs call for a new major release (+1.0.0). This | ||
| means that the PR is breaking backward compatibility. | ||
|
|
||
| -  This PR generally closes an `Enhancement` issue. It increments the minor version (0.+1.0) | ||
|
|
||
| -  This label should be used during development stages (<1.0.0) only. These PRs call for a new minor release during development (0.+1.0) that **will** break backward compatibility. | ||
|
|
||
| -  This PR contains changes to the internal API. It won't | ||
| trigger a release, but it will be reported in the changelog. | ||
|
|
||
| -  See above. This PR won't trigger a release, but it will be | ||
| reported in the changelog. | ||
|
|
||
| -  This PR will **not** trigger a release. | ||
|
|
||
| -  This PR will force the trigger of a release. | ||
|
|
||
| #### Other labels | ||
|
|
||
| - : These PRs don't seem right. They actually seem so not | ||
| right that they won't be further processed. This label invalidates a | ||
| Hacktoberfest contribution. If you think this is wrong, start a | ||
| discussion in the relevant issue (or open one if missing). Reviewers | ||
| are asked to give an explanation for the use of this label. | ||
|
|
||
| ### Good First Issues | ||
|
|
||
| Good First Issues are issues that are either very simple, or that help | ||
| the contributor get to know the programs or the languages better. We use | ||
| it to help contributors with less experience to learn and familiarise | ||
| with Git, GitHub, Python3, and physiology. We invite more expert | ||
| contributors to avoid those issues, leave them to beginners and possibly | ||
| help them out in the resolution of the issue. However, if the issue is | ||
| left unassigned or unattended for long, and it's considered important or | ||
| urgent, anyone can tackle it. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| ## Issues and Milestones | ||
|
|
||
| At `physiopy`, we use Issues and Milestones to keep track of and | ||
| organise our workflow. **Issues** describe pieces of work that need to | ||
| be completed to move the project forwards. We try to keep them as simple | ||
| and clear as possible: an issue should describe a unitary, possibly | ||
| small piece of work (unless it's about refactoring). Don't be scared of | ||
| opening many issues at once, if it makes sense! Just check that what | ||
| you're proposing is not listed in a previous issue (open or closed) yet | ||
| (we don't like doubles). Issues get labelled. That helps the | ||
| contributors to know what they're about. Check the label list to know | ||
| what types are there, and use them accordingly! Issues can also be | ||
| **assigned**. If you want to work on an assigned issue, ask permission | ||
| first! - **Milestones** set the higher level workflow. They sketch | ||
| deadlines and important releases. Issues are assigned to these | ||
| milestones by the maintainers. If you feel that an issue should be | ||
| assigned to a specific milestone but the maintainers have not done so, | ||
| discuss it in the issue chat or in Gitter! We might have just missed it, | ||
| or we might not (yet) see how it aligns with the overall project | ||
| structure/milestone. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,85 @@ | ||
| ## Pull Requests | ||
|
|
||
| To improve understanding pull requests "at a glance" and use the power | ||
| of `auto`, we use the labels listed above. Multiple labels can be | ||
| assigned to a PR - in fact, all those that you think are relevant. We | ||
| strongly advise to keep the changes you're introducing with your PR | ||
| limited to your original goal. Adding to the scope of your PR little | ||
| style corrections or code refactoring here and there in the code that | ||
| you're already modifying is a great help, but when they become too much | ||
| (and they are not relevant to your PR) they risk complicating the nature | ||
| of the PR and the reviewing process. It is much better to open another | ||
| PR with the objective of doing such corrections! Moreover, if you're | ||
| tempted to assign more than one label that would trigger a release (e.g. | ||
| bug and minormod or bug and majormod, etc.), you might want to split your PR | ||
| instead. When opening a pull request, assign it at least one label. | ||
|
|
||
| We encourage you to open a PR as soon as possible - even before you | ||
| finish working on them. This is useful especially to you - so that you | ||
| can receive comments and suggestions early on, rather than having to | ||
| process a lot of comments in the final review step! However, if it's an | ||
| incomplete PR, please open a **Draft PR**. That helps us process PRs by | ||
| knowing which one to have a look first - and how picky to be when doing | ||
| so. | ||
|
|
||
| Reviewing PRs is a time consuming task and it can be stressful for both | ||
| the reviewer and the author. Avoiding wasting time and the need of | ||
| little fixes - such as fixing grammar mistakes and typos, styling code, | ||
| or adopting conventions - is a good start for a successful (and quick) | ||
| review. Before graduating a Draft PR to a PR ready for review, please | ||
| check that: | ||
|
|
||
| - You did all you wanted to include in your PR. If at a later stage | ||
| you realize something is missing and it's not a minor thing, you | ||
| will need to open a new PR. | ||
| - If your contribution contains code or tests, you ran and passed all | ||
| of the tests locally with [pytest](#automatic-testing). | ||
| - If you're writing documentation, you built it locally with | ||
| sphinx and the format is what you intended. | ||
| - Your code is harmonious with the rest of the code - no repetitions | ||
| of any sort! | ||
|
|
||
| Your code respects the [adopted Style](#style-guide), especially if: | ||
|
|
||
| - Your code is lintered adequately and respects the [PEP8](https://www.python.org/dev/peps/pep-0008/) convention. | ||
| - Your docstrings follow the [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) convention. | ||
| - There are no typos or grammatical mistakes and the text is fluid. | ||
|
|
||
| - The code is sufficiently commented and the comments are clear. | ||
|
|
||
| - Your PR title is clear enough to be meaningful when appended to the version changelog. | ||
|
|
||
| - You have the correct labels. | ||
|
|
||
|
|
||
| ### Before merging | ||
|
|
||
| To be merged, PRs have to: | ||
|
|
||
| 1. Pass all the CircleCI tests, and possibly all the codecov checks. | ||
| 2. Have the necessary amount of approving reviews, even if you're a | ||
| long time contributor. | ||
|
|
||
| Note : You can ask one (or more) contributor to do | ||
| that review, if you think they align more with the content of your | ||
| PR. You need **one** review for documentation, tests, and small | ||
| changes, and **two** reviews for bugs, refactoring and enhancements. | ||
| 3. Have at least a release-related label (or a `Skip | ||
| release` label). | ||
| 4. Have a short title that clearly explains in one sentence the aim of | ||
| the PR. | ||
| 5. Contain at least a unit test for your contribution, if the PR | ||
| contains code (it would be better if it contains an integration or | ||
| function test and all the breaking tests necessary). If you're not | ||
| confident about writing tests, it is possible to refer to an issue | ||
| that asks for the test to be written, or another (Draft) PR that | ||
| contains the tests required. | ||
|
|
||
| As we're trying to maintain at least 90% code coverage, you're strongly | ||
| encouraged to write all of the tests necessary to keep coverage above | ||
| that threshold. If coverage drops too low, you might be asked to add | ||
| more tests and/or your PR might be rejected. See the [Automatic testing](#automatic-testing) section. | ||
|
|
||
| Don't merge your own pull request! That's a task for the main reviewer | ||
| of your PR or the project manager. Remember that the project manager | ||
| doesn't have to be a reviewer of your PR! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| ## Under development | ||
| We're still building this section of the guide, so stay tuned (or help!) | ||
|
|
||
| We'd like to provide more information on some of the tools you may use in your contributions to Physiopy such as | ||
|
|
||
| ### Pre-commit | ||
| ### CircleCI | ||
| ### Pytest | ||
| ### Pypi | ||
| ### OSF/test data | ||
|
|
||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,109 @@ | ||
| ## Reviewing PRs | ||
|
|
||
| Reviewing PRs is an extremely important task in collaborative | ||
| development. In fact, it is probably the task that requires the most | ||
| time in the development, and it can be stressful for both the reviewer | ||
| and the author. Remember that, as a PR Reviewer, you are guaranteeing | ||
| that the changes work and integrate well with the rest of the | ||
| repository, hence **you are responsible for the quality of the | ||
| repository and its next version release**. If they don't integrate | ||
| well, later PR reviewers might have to ask for broader changes than | ||
| expected. | ||
|
|
||
| There are many best practices to review code online, for | ||
| instance [this medium blog post](https://medium.com/an-idea/the-code-review-guide-9e793edcd683), but | ||
| here are some good rules of thumbs that we need to follow while | ||
| reviewing PRs: | ||
|
|
||
| - Be **respectful** to the PR authors and be clear in what you are | ||
| asking/suggesting - remember that, like you, they are contributing | ||
| their spare time and doing their best job! | ||
|
|
||
| - If there is a *Draft PR*, you can comment on its development in the | ||
| message board or making "Comment" reviews. Don't ask for changes, | ||
| and especially, **don't approve the PR** | ||
|
|
||
| - If the PR graduated *from Draft to full PR*, check that it follows the | ||
| sections [Pull requests](#pull-requests) and [Style Guide](#style-guide) of these | ||
| guidelines. If not, invite the author to do so before starting a | ||
| review. | ||
| - **Don't limit your review to the parts that are changed**. Look at | ||
| the entire file, see if the changes fit well in it, and see if the | ||
| changes are properly addressed everywhere in the code - in the | ||
| documentation, in the tests, and in other functions. Sometimes the | ||
| differences reported don't show the full impact of the PR in the | ||
| repository! | ||
| - If your want to make Pull Requests an educational process, invite | ||
| the author of the PR to make changes before actually doing them | ||
| yourself. Request changes via comments or in the message board or by | ||
| checking out the PR locally, making changes and then submitting a PR | ||
| to the author's branch. | ||
| - If you decide to use the suggestion tool in reviews, or to start a | ||
| PR to the branch under review, please alert the Project Manager. | ||
| Bots might automatically assign you contribution types that will | ||
| have to be removed (remember, your contribution in this case is | ||
| "Reviewer"). Instead of starting a PR to the branch under review, | ||
| think about opening a new PR with those modifications (unless they | ||
| are needed to pass tests), and alert the Main Reviewer. In any case | ||
| **don't commit directly to the branch under review**! | ||
| - If you're reviewing documentation, build it locally with [`sphinx-build`](https://www.sphinx-doc.org/en/master/man/sphinx-build.html) command. | ||
| - If you're asking for changes, **don't approve the PR**. Approve it | ||
| only after everything was sufficiently addressed. Someone else might | ||
| merge the PR in taking your word for granted. | ||
| - If you are the main reviewer, and the last reviewer required to | ||
| approve the PR, merge the PR! | ||
|
|
||
| Before approving and/or merging PRs, be sure that: | ||
|
|
||
| - All the tests in CircleCI/Azure pass without errors. | ||
| - Prefereably, codecov checks pass as well. If they don't, discuss | ||
| what to do. | ||
| - The title describes the content of the PR clearly enough to be | ||
| meaningful on its own - remember that it will appear in the version | ||
| changelog! | ||
| - The PR has the appropriate labels to trigger the appropriate version | ||
| release and update the contributors table. | ||
|
|
||
| ### Main reviewer | ||
|
|
||
| At `physiopy` we use the *Assignees* section of a PR to mark the | ||
| **main reviewer** for that PR. The main reviewer is the primary person | ||
| responsible **for the quality of the repository and its next version release**, | ||
| as well as **for the behaviour of the other reviewers**. | ||
|
|
||
| ***The main reviewer takes care of the reviewing process of the PR, in particular:*** | ||
|
|
||
| - Invites the reviewers to finish their review in a relatively | ||
| short time. | ||
|
|
||
| - Checks that all elements of this document were respected, | ||
| especially the part about [Pull Requests](#pull-requests). | ||
|
|
||
| - Invites other Reviewers to respect this document, especially | ||
| the part about [reviews](#reviewing-prs), helps them in doing | ||
| so, and checks that they do. | ||
|
|
||
| - If a Reviewer keeps not respecting this document, flags them | ||
| to the project manager. | ||
|
|
||
| - Decides what to do in case of a coverage decrease (in | ||
| *codecov/patch*). | ||
|
|
||
| ***In case of missing tests or updates to user documentation:*** | ||
|
|
||
| - Asks for more documentation or tests before approving the | ||
| PR, *or* | ||
|
|
||
| - Checks that the appropriate issues have been opened to | ||
| address the lack of documentation or tests (1 issue per item), *or* | ||
|
|
||
| - Double-checks that the title is clear and the labels are correct to | ||
| trigger an appropriate `auto` release - feel free to change them. | ||
|
|
||
| - Main reviewer **Is the one that is going to merge the PR.** | ||
|
|
||
| ***After the PR has been merged and a new release has been triggered, checks that:*** | ||
|
|
||
| - The documentation was updated correctly (if changed). | ||
| - The Pypi version of the repository coincides with the new release (if changed). | ||
| - New contributors or forms of contributions were correctly added in the README (if changed). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| ## Under development | ||
| We're still building this section of the guide, so stay tuned (or help!) | ||
|
|
||
|
|
Oops, something went wrong.