Welcome to the DBIC Handbook repository located at github.com/dbic/handbook !
We're so excited you're here and want to contribute.
We hope that 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.
Been here before? Already know what you're looking for in this guide? Jump to the following sections:
- Joining the DBIC community
- Contributing through GitHub
- Understanding issues
- Writing in markdown
- Make a change with a pull request
- Example pull request
- Fixing Remark errors from Travis
- Recognizing contributions
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!
Moving forward, we encourage all members to contribute here on GitHub.
As a reminder, we expect that all contributions adhere to our Code of Conduct.
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.
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.
The current list of labels are here and include:
If you feel that you can contribute to one of these issues, we especially encourage you to do so!
Ongoing discussions benefit from broad feedback. This label is used to highlight issues where decisions are being considered, so please join the conversation!
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.
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. Remark preserves consistent markdown styling across the contributions. 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.
We have deployed a continuous integrator (circle CI) to further allow for integrating changes continuously. The CI is testing that the changes are inline with our standard styling.
GitHub has a helpful page on getting started with writing and formatting on GitHub.
We are using mkdocs to render our handbook. Please follow these instructions if you would like to build the handbook locally.
To begin please follow this link to install mkdocs locally.
2. Download the DBIC Handbook repository onto your computer
This can be done by clicking the green button on the right titled "Clone or download"
Please go here and install our theme - material. The terminal command is
pip install mkdocs-material
This location will have the same files you see on our main handbook page. Note: A finder window may not show the hidden files (those that start with a period i.e. .remarkrc)
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. You may enter that into your browser and this will bring up the handbook!
We appreciate all contributions to the DBIC Handbook. THANK YOU for helping us build this useful resource.
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!
Try to keep the changes focused. If you submit a large amount of work in all in one go it will be much more work for whomever is reviewing your pull request. Please detail the changes you are attempting to make.
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
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.
We use a linter called Remarkjs to ensure all of our Markdown documents are consistent and well-styled. This commonly produces errors, which are flagged by Travis CI, a continuous integration service. When Travis returns an error, use the following process to resolve the issue:
Remark-CLI can be installed via npm, which is part of the NodeJS distribution.
To install the packages we use for our style guide, the following command will work on most command lines:
npm install `cat npm-requirements.txt`
The equivalent command on PowerShell is:
npm install @(cat npm-requirements.txt)
Please go to the directory where the flagged file is and run remark like this:
remark flagged_file.md -o flagged_file_fixed.md
Please confirm this has fixed the file. To do this, please run this:
remark flagged_file_fixed.md --frail
This command will indicate whether this file now conforms to the style guide.
If it passes, replace
flagged_file.md with the contents of
add and commit the change:
mv flagged_file_fixed.md flagged_file.md git add flagged_file.md git commit -m 'STY: Fixed Markdown style'
TODO: decide on either we should establish a formal procedure. yoh thinks it might not be needed to be that formal for starters.
DBIC follows the all-contributors handbook, so we welcome and recognize all contributions from documentation to testing to code development. You can see a list of current contributors in the DBIC Handbook.