Merge pull request #58 from m-miedema/DOC/CGuide

Migrating existing Contributor Guide to wiki-style format

Author: m-miedema

docs/community/contributor-guide.md

@@ -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.

docs/community/contributorfile.md

@@ -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
+
+- ![Documentation](https://img.shields.io/badge/-Documentation-1D70CF?style=flat-square) Improvements or additions to documentation. This
+  category includes (but is not limited to) docs pages, docstrings,
+  and code comments. 
+
+- ![Duplicate](https://img.shields.io/badge/-Duplicate-CFD3D7?style=flat-square) Whatever this is, it exists already! Maybe it's a closed
+  Issue/PR, that should be reopened. 
+
+- ![Enhancement](https://img.shields.io/badge/-Enhancement-A2EEEF?style=flat-square) New features added or requested. This normally goes with a `minormod` label for PRs.
+
+- ![Outreach](https://img.shields.io/badge/-Outreach-0E8A16?style=flat-square) 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. 
+
+- ![Paused](https://img.shields.io/badge/-Paused-F7C38C?style=flat-square) Issue or PR should not be worked on until the resolution of other issues or PRs.
+
+- ![released](https://img.shields.io/badge/-released-ffffff?style=flat-square) This Issue or PR has been released. 
+
+- ![Testing](https://img.shields.io/badge/-Testing-FFB5B4?style=flat-square) This is for testing features, writing tests or producing testing code. Both user testing and CI testing!
+
+- ![Urgent](https://img.shields.io/badge/-Urgent-FFF200?style=flat-square) If you don't know where to start, start here! This is probably related to a milestone due soon!
+
+### Issue-only labels
+
+- ![BrainHack](https://img.shields.io/badge/-BrainHack-000000?style=flat-square) This issue is suggested for BrainHack participants!
+
+- ![Bug](https://img.shields.io/badge/-Bug-D73A4A?style=flat-square) Something isn't working. It either breaks the code or has an
+  unexpected outcome.
+
+- ![Community](https://img.shields.io/badge/-Community-E2C7FC?style=flat-square) This issue contains information about the `physiopy`
+  community (e.g. the next developer call)
+ 
+- ![Discussion](https://img.shields.io/badge/-Discussion-1C778C?style=flat-square) Discussion of a concept or implementation. These Issues
+  are prone to be open ad infinitum. Jump in the conversation if you
+  want!
+
+- ![Good first issue](https://img.shields.io/badge/-Good%20first%20issue-4E2A84?style=flat-square) 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.
+
+- ![Hacktoberfest](https://img.shields.io/badge/-Hacktoberfest-FF7518?style=flat-square) 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**.
+
+- ![Help wanted](https://img.shields.io/badge/-Help%20wanted-57DB1A?style=flat-square) Extra attention is needed here! It's a good place to have a look!
+
+- ![Refactoring](https://img.shields.io/badge/-Refactoring-9494FF?style=flat-square) 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.
+
+- ![Question](https://img.shields.io/badge/-Question-D876E3?style=flat-square) Further information is requested, from users to
+  developers. Try to respond to this!
+  
+- ![Wontfix](https://img.shields.io/badge/-Wontfix-ffffff?style=flat-square) This will not be worked on, until further notice.
+
+### PR-only labels
+
+#### Labels for semantic release and changelogs
+
+- ![BugFIX](https://img.shields.io/badge/-BugFIX-D73A4A?style=flat-square) These PRs close an issue labelled `Bug`. They also increase
+  the semantic versioning for fixes (+0.0.1).
+
+ - ![dependencies](https://img.shields.io/badge/-dependencies-0366D6?style=flat-square) Pull requests that update a dependency file
+
+- ![Documentation](https://img.shields.io/badge/-Documentation-1D70CF?style=flat-square) See above. This PR won't trigger a release, but it will be reported in the changelog.
+
+- ![Majormod](https://img.shields.io/badge/-Majormod-05246D?style=flat-square) These PRs call for a new major release (+1.0.0). This
+  means that the PR is breaking backward compatibility.
+
+- ![Minormod](https://img.shields.io/badge/-Minormod-05246D?style=flat-square) This PR generally closes an `Enhancement` issue. It increments the minor version (0.+1.0)
+
+- ![Minormod-breaking](https://img.shields.io/badge/-Minormod&ndash;breaking-05246D?style=flat-square) 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. 
+
+- ![Internal](https://img.shields.io/badge/-Internal-ffffff?style=flat-square) This PR contains changes to the internal API. It won't
+  trigger a release, but it will be reported in the changelog.
+
+- ![Testing](https://img.shields.io/badge/-Testing-FFB5B4?style=flat-square) See above. This PR won't trigger a release, but it will be
+  reported in the changelog.
+
+- ![Skip release](https://img.shields.io/badge/-Skip%20release-ffffff?style=flat-square) This PR will **not** trigger a release.
+
+- ![Release](https://img.shields.io/badge/-Release-ffffff?style=flat-square) This PR will force the trigger of a release.
+
+#### Other labels
+
+- ![Invalid](https://img.shields.io/badge/-Invalid-960018?style=flat-square): 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.

docs/contributors-guide/codebase/index.md

@@ -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.

docs/contributors-guide/codebase/labels.md

@@ -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!

docs/contributors-guide/codebase/opening-issues.md

@@ -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
+
+
+

docs/contributors-guide/codebase/opening-prs.md

@@ -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).

docs/contributors-guide/codebase/plug-ins.md

@@ -0,0 +1,4 @@
+## Under development
+We're still building this section of the guide, so stay tuned (or help!)
+
+