Contributing to the DBIC Handbook

Welcome to the DBIC Handbook repository, located at github.com/dbic/handbook. We're so excited you're here and want to contribute!

These guidelines are designed to make it as easy as possible to get involved. If you have any questions that aren't discussed below, please let us know by opening an issue.

Joining the community

DBIC - the Dartmouth Brain Imaging Center - is a growing community of neuroimaging enthusiasts, and we want to make our resources accessible to and engaging for as many researchers as possible.

How do you know that you're a member of the DBIC community? You're here! You know that DBIC exists! You're officially a member of the community. It's THAT easy! Welcome!

Most of our discussions take place here in GitHub issues. We also have the mrusers mailing list (mrusers@groups.dartmouth.edu) for general DBIC announcements and discussion.

Moving forward, we encourage all members to contribute here on GitHub.

DBIC is a Dartmouth facility rather than a standalone open-source community, so this handbook does not carry a code of conduct of its own. Conduct in these spaces is governed by Dartmouth's Nondiscrimination and Anti-Harassment Policy. If you experience or witness harassment, discrimination or retaliation, you can report it to the Office of Equal Opportunity, Accessibility, and Title IX (EOATIX) at (603) 646-0922 or Parkhurst Hall, Suite 05, through the Title IX reporting form, or anonymously via the Dartmouth Integrity Helpline.

Contributing through GitHub

Git is a really useful tool for version control. GitHub sits on top of git and supports collaborative and distributed working.

We know that it can be daunting to start using git and GitHub if you haven't worked with them in the past, but the DBIC Handbook maintainers are here to help you figure out any of the jargon or confusing instructions you encounter!

In order to contribute via GitHub you'll need to set up a free account and sign in. Here are some instructions to help you get going. Remember that you can ask us any questions you need to along the way.

Understanding issues

Every project on GitHub uses issues slightly differently.

The following outlines how DBIC developers think about communicating through issues.

Issues are individual pieces of work that need to be completed or decisions that need to be made to move the project forwards. A general guideline: if you find yourself tempted to write a great big issue that is difficult to describe as one unit of work, please consider splitting it into two or more issues.

Issues are assigned labels which explain how they relate to the overall project's goals and immediate next steps.

Issue labels

The current list of labels are here and include:

These issues contain a task that a member of the team has determined we need additional help with.

If you feel that you can contribute to one of these issues, we especially encourage you to do so!
These issues hold discussions where we're especially eager for feedback.

Ongoing discussions benefit from broad feedback. This label is used to highlight issues where decisions are being considered, so please join the conversation!
These issues are related to building and supporting the DBIC community.

In addition to the handbook itself, we are dedicated to creating a healthy community. These issues highlight pieces of work or discussions around how we can support our members and make it easier to contribute.

Writing in Markdown

The handbook documents follow the Markdown Style Guide.

You can validate your changes against the guide using remark which works as a standalone command line tool as well as a plugin for various text editors. It preserves consistent Markdown styling across the contributions.

One rule the linter cannot enforce for us: MkDocs renders with Python-Markdown, which needs four spaces to indent the content of a nested list item, where CommonMark accepts two. Nested list content indented by two spaces lints cleanly and then renders flattened into its parent, so keep it at four spaces. Please ensure before submitting a contribution that you do not have any linter errors in your text editor. You can also use prettier to automatically correct some of the style issues that might be found in the proposed changes.

Every pull request is checked by GitHub Actions: the workflow lints the Markdown sources with remark, builds the handbook with MkDocs, and verifies that no internal link is broken. External links are checked weekly instead, so that a third-party outage cannot fail your pull request. A separate workflow regenerates the changelog from the merged pull request titles on every push to master and commits it back, but only when the content has actually changed. Release commits are skipped so that a changelog a maintainer curated for a release is not immediately overwritten. The workflow definitions live in .github/workflows/.

GitHub has a helpful page on getting started with writing and formatting on GitHub.

Building the handbook using MkDocs

We are using MkDocs to render our handbook. Please follow these instructions if you would like to build the handbook locally.

1. Clone the DBIC Handbook repository

Clone the repository with git (TODO: link to docs). You will need git to contribute the changes you make later.

2. Install the build dependencies

From the root of your clone, run pip install -r requirements.txt. That installs MkDocs together with the Material theme at the versions the handbook is built with.

3. In the terminal (command line) navigate to your local version of the handbook

This location will have the same files you see on our main handbook page. Note: a Finder window may not show hidden files (those that start with a period, e.g. .remarkrc).

4. Ready to build!

Using the terminal (command line) please enter mkdocs serve. This will allow you to see a local version of the handbook. The local address will be http://127.0.0.1:8000 or localhost:8000. You may enter that into your browser and this will bring up the handbook!

Making a change with a pull request

We appreciate all contributions to the DBIC Handbook. THANK YOU for helping us build this useful resource.

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

This allows other members of the DBIC Handbook 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.

2. Fork this repository to your profile

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

Make sure to keep your fork up to date with the upstream repository, otherwise you can end up with lots of dreaded merge conflicts.

3. Make the changes you've discussed

Try to keep the changes focused. If you submit a large amount of work all in one go, it will be much more work for whoever is reviewing your pull request. Please detail the changes you are attempting to make.

4. Submit a pull request

Please keep the title of your pull request short but informative - it will appear in the changelog.

Use one of the following prefixes in the title of your pull request:

[ENH] - enhancement of the handbook that adds a new feature or support for a new data type
[FIX] - fix of a typo or language clarification
[INFRA] - changes to the infrastructure automating the handbook release (for example building HTML docs etc.)
[MISC] - everything else including changes to the file listing contributors

If you are opening a pull request to obtain early feedback, but the changes are not ready to be merged (a.k.a. Work in Progress pull request) please use a draft pull request.

A member of the DBIC Handbook team will review your changes to confirm that they can be merged into the main codebase.

A review will probably consist of a few questions to help clarify the work you've done. Keep an eye on your GitHub notifications and be prepared to join in that conversation.

You can update your fork of the DBIC Handbook and the pull request will automatically update with those commits. You don't need to submit a new pull request when you make a change in response to a review.

GitHub has a nice introduction to the pull request workflow, but please get in touch if you have any questions.

Example pull request

Example-Contribution

Fixing remark errors reported by CI

We use a linter called remark-lint to ensure all of our Markdown documents are consistent and well-styled. It runs in the Markdown style job of the CI workflow, and it commonly flags errors. When that job fails, use the following process to resolve the issue.

1. Install Node.js / npm

We use a Markdown linter written in JavaScript. To run JavaScript tools on the command line, please download and install Node.js.

2. Install remark and our style guide

The linter and the presets it needs are declared in package.json, so from the root of your clone run:

npm install

3. Check the sources

The same command CI runs is available as an npm script:

npm run lint

It reports every file that does not conform to the style guide.

4. Fix the flagged documents

Each warning names the file, the line and the rule, so fix them in place and re-run npm run lint until it is quiet, then commit the change:

git add -u
git commit -m 'STY: Fixed Markdown style'

Do not reach for remark's --output to reformat automatically: it rewrites the whole tree to its own defaults (* bullets, two-space nesting), which both fails our lint configuration and flattens nested lists in the rendered site. The changelog workflow is the one exception, and only because the file it formats is generated, has no nested lists, and is passed an explicit bullet style.