Bids-specification: add CONTRIBUTING.md with links/specs of style guide

[edickie]

I realized as I was reading through the raw specification file that I was hesitant to suggest style edits because I didn't know if any decisions had been made about which _flavor_ of markdown we are using, so I didn't know how to suggest changes so things like tables and file paths/directory trees.

I contributing guide with a record of markdown formatting decisions would be useful.

Specifically, the things I wondered about right away were:

• are all the tables still in html because of a formatting decision or can they be converted to markdown tables
• is there a decided formatting structure for directory trees? (should they look like tree outputs?) of just bullet-ed/tabbed?

[effigies]

These are in a somewhat different vein, but I would also introduce a couple suggestions for style that are mostly aimed at having readable diffs and helping the review process focus on content:

• New sentences start on new lines. This makes the scope of the change immediately obvious; single-word changes should be +/- one line, and moderate rewording might affect a couple lines, but never surrounding sentences. I've found this practice helpful when co-authoring LaTeX documents, and RST documentation for fMRIPrep. (I've also found a reference: semantic linefeeds)
• Wrap lines at some reasonable character count, but don't obsess over getting close to the character limit to the point of infecting unrelated lines (e.g., if shortening a line slightly, pulling a word from the next line is generally not necessary even when it fits).
• Style cleanups, when absolutely necessary, should have their own, clearly marked, commits.

[chrisgorgo]

We are most likely going to adhere to http://www.cirosantilli.com/markdown-style-guide/. I need to make remark-lint to cooperate first.

[emdupre]

Our contributing guide should also include more general information-- particularly on getting started with GitHub, since many contributors may be joining for the first time !

[KirstieJane]

+1 to @emdupre's point. Feel free to grab anything from the starter kit that make sense! https://github.com/bids-standard/bids-starter-kit/blob/master/CONTRIBUTING.md

[chrisgorgo]

This is also a good tutorial: https://egghead.io/lessons/javascript-introduction-to-github

[KirstieJane]

Hey folks in the thread - I've been mostly offline for a few day - is anyone working on the contributors guide? I can take the lead if that's helpful....I might need a week or so to get it done but happy to be assigned unless anyone else wants to?! (tagging @park-patrick as he did lots of work with me on the bid-starter-kit guidelines??)

[chrisgorgo]

Thanks for offering to help! We definitely need more documentation for contributors. Happy to "assign" you to this issue, but you will need to accept the invitation to join bids-standard org (should be in your email).

[KirstieJane]

Done! Thank you - I'd missed that :)

[chrisgorgo]

Done!

[Park-Patrick]

Hi @KirstieJane, sure I'd be open to helping! @chrisfilo could you send me an invitation as well?

[KirstieJane]

@park-Patrick - I don’t think you need to be a member. It makes sense to do the work in a pull request. I only need to be part of the organisation to be “assigned” the issue (and for other reasons - that’s why Chris had sent the invite a week ago!)

If you have time to start pulling across some of the useful points from the starter kit that would be great!

[Park-Patrick]

started the pull request here! #44