Contributing guidelines [Join the conversation]

[KirstieJane]

I'd really like lots of people to contribute to this project, so we need super clear contributing guidelines!

I've collaboratively written a few, I think this one is my favourite. We'll need to figure out which parts to keep etc, and we can do that in part at the sprint next week, but it would be great to have something in place or in a pull request to get us started ✨

---

Update

Here's a master list from the comments below that need to be incorporated into the CONTRIBUTING.md file

• Pull request and issue templates (and why we have them)
• How do we acknowledge contributors
• Reformat & edit section on how to write a chapter
  • The current section isn't very easy to read - one big list of bullet points. A figure would go a long way to making this easier!
  • Also need to add guides for someone outside of the core team contributing a chapter - how do they start and make sure they aren't repeating work already in progress or out of scope?
• Need to explain about branches & forks etc! Bring in some pictures from git flow to help explain this.
  • Note - the answer here is to link to the version control chapter rather than reinvent the wheel.
  • Here's a nice blog post: https://nvie.com/posts/a-successful-git-branching-model
• Try to stay up to date with master/upstream as best you can to avoid merge requests!
  • To do that you'll need to syncing branches and forks with upstream: https://github.com/KirstieJane/STEMMRoleModels/wiki/Syncing-your-fork-to-the-original-repository-via-the-browser
• Please don't re-write history! (rebase, reflog!)
• Style guide - markdown on separate lines please
• Try to write good commit messages: https://chris.beams.io/posts/git-commit/
• Its fine to have lots of commits - including ones that break code. A good rule of thumb is to push up to GitHub when you do have passing tests then the CI has a good chance of passing everything 😸

Lets also make a GOVERNANCE.md document

• Governance of the project, how are decisions made?
• What is a maintainer, how do you become one?

Minor fixes as spotted by @sdruskat in #244

• Replace BIDS Starter Kit string with The Turing Way where appropriate.
• Acknowledge the source of the text somewhere, depending on license, etc.

---

A list of contributing guidelines that @KirstieJane (et al) have written/edited for other projects:

• https://github.com/ME-ICA/tedana/blob/master/CONTRIBUTING.md
• https://github.com/WhitakerLab/scona/blob/master/CONTRIBUTING.md
• https://github.com/bids-standard/bids-starter-kit/blob/master/CONTRIBUTING.md
• https://hackmd.io/7YIC0zYOR1m6ldI5W_8K9w# (copied from a private project)

It would be SUPER helpful if anyone wanted to pull in the good stuff from any of these into our CONTRIBUTING guidelines ✨ Tagging @rainsworth because we've had this conversation 👾

[KirstieJane]

• Please open an issue first!
• Make clear that we encourage updating the issue with a summary of the discussion as it goes along to make it super easy to read.
• And open a pull request early.
• Use the WIP marker if you're not ready for the review ✅
• You can submit pull requests to the OTHER PERSON'S BRANCH.
• Responsibilities of a maintainer to the project - how do you progress to a maintainer? How do you progress beyond a 1 off contributor?
• Need to explain about branches & forks etc! Bring in some pictures from git flow to help explain this.
• Syncing branches & forks with "upstream"

[annakrystalli]

I really like this blogpost. It's quite detailed and comprehensive but it helped me understand where the conventions come from: https://nvie.com/posts/a-successful-git-branching-model/

[KirstieJane]

• Please don't re-write history! (rebase, reflog!)

[KirstieJane]

• Try to write good commit messages: https://chris.beams.io/posts/git-commit/
• Its fine to have lots of commits - including ones that break code. A good rule of thumb is to push up to GitHub when you do have passing tests then the CI has a good chance of passing everything 😸

[KirstieJane]

• Try to stay up to date with master/upstream as best you can to avoid merge requests!

[KirstieJane]

• Add a sentence near the top (or the bottom) to make clear that following everything perfectly is not required, we're mostly just really excited that anyone is here and taking part ✨ ---- maybe also add to Ways of Working doc Add a ways of working document #26

[pherterich]

Moved from #39

• add new labels
• explain how to use templates for various parts

[pherterich]

• @pherterich to add discussion on WIP chapter processes

[rainsworth]

• Incorporate advice from the pre-reading for the Technical Writing 101 class at Collaborations Workshop 2019 into the contributing guidelines.

[rainsworth]

re: quite a few comments above about syncing/staying up to date with upstream

Add brief section (and point to section that already exists in the book?) about how to reset local fork to upstream/master (for when you have changes on your local fork that you do not want to save and want to start over from the current state of the original repo).

For example:

> git remote add upstream https://github.com/alan-turing-institute/the-turing-way
> git remote -v     
origin	https://github.com/rainsworth/the-turing-way.git (fetch)
origin	https://github.com/rainsworth/the-turing-way.git (push)
upstream	https://github.com/alan-turing-institute/the-turing-way (fetch)
upstream	https://github.com/alan-turing-institute/the-turing-way (push)
> git fetch upstream
> git reset --hard upstream/master
> git clean -f
> git push origin master --force

[rainsworth]

FYI I'm going to work on the section Making a change with a pull request here at Collaborations Workshop 2019