Contributing documentation guidelines

Steps

1. Comment on an existing issue or open a new issue referencing your addition.

This allows other members of the fMRIPrep development team to confirm that you aren't overlapping with work that's currently underway and that everyone is on the same page with the goal of the work you're going to carry out.

A pool of proposed documentation improvements is found here https://github.com/orgs/poldracklab/projects/2, please feel free to annotate your willingness to address any particular issue adding a comment with your name.

This blog is a nice explanation of why putting this work in upfront is so useful to everyone involved.

2. Fork the fMRIPrep repository to your profile.

This is now your own unique copy of fMRIPrep. Changes here won't effect anyone else's work, so it's a safe space to explore edits to the code!

3. Clone your forked fMRIPrep repository to your machine/computer

While you can edit files directly on github, sometimes the changes you want to make will be complex and you will want to use a text editor that you have installed on your local machine/computer. (One great text editor is vscode).

In order to work on the code locally, you must clone your forked repository.

To keep up with changes in the fmriprep repository, add the "upstream" fmriprep repository as a remote to your locally cloned repository.

git remote add upstream https://github.com/poldracklab/fmriprep.git

Make sure to keep your fork up to date with the upstream repository.

4. Create a branch where you will be working on.

It is very important that you create a new branch so you keep your local copy of the repository clean at all times. To create a new branch, issue the following command:

git checkout -b docs/a-new-contribution upstream/master

Please MAKE SURE THE NEW BRANCH NAME's STARTS WITH docs/. The new branch names is the argument given right after the -b flag. Please replace the a-new-contribution section of the branch name with a more descriptive (and preferably shorter) name.

5. Make the changes you've signed-up for in step 1.

Try to keep the changes focused. It can also be helpful to test your changes locally, using an fMRIPrep development environment.

You can build the docs locally executing in your local fMRIPrep folder

make SPHINXOPTS="-W" -C docs html

(eg. Code-Server Development Environment has a terminal option to execute commands).

This command will go into the /docs folder and build standalone docs in your local ../fmriprep/docs/_build/html/ folder.

Once you are satisfied with your local changes, add/commit/push them to the branch on your forked repository.

6. Submit a pull request.

A member of the development team will review your changes to confirm that they can be merged into the main code base.

The title of Pull-Requests to improve documentation should begin with a DOC: prefix (example)

For example: DOC: Add one more Q&A to the FAQ