[MISC] edit contributing guide #44
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,43 @@ | ||
|
|
||
| # Contributing to the BIDS Specification | ||
|
|
||
| **Welcome to the BIDS Specification repository!** | ||
|
|
||
| *We're so excited you're here and want to contribute.* | ||
|
|
||
|
There was a problem hiding this comment. I don't think the BIDS Specification will want all the emojis from the starter kit. Maybe have a think about how this can be formalised a little while also still being friendly! There was a problem hiding this comment. yeah wasn't sure what we wanted to do about those, but maybe we can just stick to bold / italics then? There was a problem hiding this comment. I think just bold and italics is a good starting point ! We can add emojis back in later if we think it's missing something :) There was a problem hiding this comment. hey @Park-Patrick Thank you for writing this up! I liked that the guide felt digestible throughout and easy to understand (especially for those that it maybe their first time navigating GitHub). The example you provided is great! For the 'Making a change with a pull request' I suppose that was more for the starters kit? I think the principle is consistent, just in regards to the specification. I noticed that there were some double bracketed terms (i.e. in 1 (Comment on an existing issue...) the second paragraph of [This blog][dont-push-pull-request]) I wasn't sure if you meant them to linking elsewhere? I think with Kirstie's suggestions (of adding the linter and continuous integration) will make this a nice contributing guide! One thing that maybe considered adding is how the repo is organized (i.e. that the standard is currently in the src folder). I can help with some of this too! There was a problem hiding this comment. good catch! so some of the double bracketed terms had corresponding tags in the starter kit version, but I think some of them became obsolete so i'll either re-link or remove them. I'm not super familiar with this repo's policies for linter/CI moving forward, so it would be great to get help with that! There was a problem hiding this comment. I see! No worries! I can add what I understand from linter/CI as well. I'll work on it from your repo and PR to that |
||
| 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 through one of the many ways to [get in touch](#get-in-touch). | ||
|
|
||
| ## Table of contents | ||
|
|
||
| Been here before? Already know what you're looking for in this guide? Jump to the following sections: | ||
|
|
||
| * [Joining the BIDS community](#joining-the-community) | ||
| * [Get in touch](#get-in-touch) | ||
| * [Contributing through GitHub](#contributing-through-github) | ||
| * [Writing in markdown](#writing-in-markdown) | ||
| * [Make a change with a pull request](#making-a-change-with-a-pull-request) | ||
| * [Example pull request](#example-pull-request) | ||
| * [Recognizing contributions](#recognizing-contributions) | ||
|
|
||
| ## Joining the community | ||
|
|
||
| BIDS - the [Brain Imaging Data Structure][bids] - is a growing community of neuroimaging enthusiasts, and we want to make our resources accessible to and engaging for as many researchers as possible. | ||
|
|
||
| We therefore require that all contributions **adhere to our [Code of Conduct](CODE_OF_CONDUCT.md)**. | ||
|
|
||
| How do you know that you're a member of the BIDS community? You're here! You know that BIDS exists! You're officially a member of the community. It's THAT easy! Welcome! | ||
|
|
||
| ## Get in touch | ||
|
There was a problem hiding this comment. Was this intended to be empty? We can remove it for now or add a section about opening issue to raise discussion topics. There was a problem hiding this comment. I think we should add to this - I'm going to wait until @franklin-feingold's PR is merged to @Park-Patrick's branch and then I can add some text in there.
right? |
||
|
|
||
| ## Contributing through GitHub | ||
|
|
||
| [git][git] is a really useful tool for version control. [GitHub][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 BIDS Specification 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](https://help.github.com/articles/signing-up-for-a-new-github-account/) to help you get going. Remember that you can ask us any questions you need to along the way. | ||
|
|
||
| ## Writing in markdown | ||
|
|
||
| The specification documents follow the | ||
| [Markdown Style Guide](http://www.cirosantilli.com/markdown-style-guide/). You | ||
|
|
@@ -12,3 +49,49 @@ as well as | |
| You can also use [prettier](https://github.com/prettier/prettier) to | ||
| automatically correct some of the style issuse that might be found in the | ||
| proposed changes. | ||
|
|
||
| GitHub has a helpful page on [getting started with writing and formatting on GitHub](https://help.github.com/articles/getting-started-with-writing-and-formatting-on-github). | ||
|
|
||
| ## Making a change with a pull request | ||
|
|
||
| We appreciate all contributions to the BIDS Specification. **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 BIDS Specification 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][github-fork] the [BIDS Starter Kit repository][bids-starterkit-repo] to your profile | ||
|
There was a problem hiding this comment. I don't think this should be pointing to BIDS Starter Kit. |
||
|
|
||
| This is now your own unique copy of the BIDS Starter Kit. Changes here won't affect anyone else's work, so it's a safe space to explore edits to the code! | ||
|
|
||
|
|
||
| Make sure to [keep your fork up to date][github-syncfork] with the master repository, otherwise you can end up with lots of dreaded [merge conflicts][github-mergeconflicts]. | ||
|
|
||
| #### 3. Make the changes you've discussed | ||
|
|
||
| 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. | ||
|
|
||
| #### 4. Submit a [pull request][github-pullrequest] | ||
|
|
||
| A member of the BIDS Specification team will review your changes to confirm that they can be merged into the main codebase. | ||
|
|
||
| A [review][github-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][github-fork] of the BIDS Specification and the pull request will automatically update with those changes. 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][github-flow] to the pull request workflow, but please [get in touch](#get-in-touch) if you have any questions. | ||
|
|
||
| ## Example pull request | ||
| <img align="right" src="https://i.imgur.com/s8yELfK.png" alt="Example-Contribution"/> | ||
|
|
||
| <br> | ||
|
|
||
| <br> | ||
|
|
||
| ## Recognizing contributions | ||
|
|
||
| BIDS follows the [all-contributors][all-contributors] specification, so we welcome and recognize all contributions from documentation to testing to code development. You can see a list of current contributors in the [BIDS specification][bids-specification]. | ||
|
There was a problem hiding this comment. Could you point to the right .md file here? |
||
|
|
||
| ## Thank you! | ||
|
|
||
| You're awesome. :wave::smiley: | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you for starting this @Park-Patrick! Is this markdown style section incorporated into the file you've started? It does need to be, and it probably makes sense to add it as a section that can be linked from the table of contents.
Some explanation of what the continuous integration is doing, what linting is and why it needs to be done would be really great. ✨
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
right makes sense!
also there is an markdown section but I'll add the link to the table of contents