[MISC] edit contributing guide #44

patrick-g-h · 2018-10-11T16:22:18Z

No description provided.

KirstieJane

I'm not able to work on this much this evening, but thank you so much for getting us started @Park-Patrick!

I'll have a look again at the weekend on or Monday 😸

KirstieJane · 2018-10-11T16:42:29Z

CONTRIBUTING.md

@@ -1,14 +1,95 @@
 # Contributors guide

-## Markdown style


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. ✨

right makes sense!
also there is an markdown section but I'll add the link to the table of contents

KirstieJane · 2018-10-11T16:43:02Z

CONTRIBUTING.md

+:tada::balloon::cake: **Welcome to the BIDS Specification repository!** :cake::balloon::tada:
+
+:dizzy::hatched_chick::sunny: *We're so excited you're here and want to contribute.* :sunny::hatched_chick::dizzy:
+


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!

yeah wasn't sure what we wanted to do about those, but maybe we can just stick to bold / italics then?

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 :)

KirstieJane · 2018-10-11T16:57:28Z

Oh - also - could you change the title of this pull request to something like "updating contributing guidelines" please - it isn't very clear in the list of pull requests what we're working on here!

franklin-feingold · 2018-10-12T04:03:42Z

CONTRIBUTING.md

+:tada::balloon::cake: **Welcome to the BIDS Specification repository!** :cake::balloon::tada:
+
+:dizzy::hatched_chick::sunny: *We're so excited you're here and want to contribute.* :sunny::hatched_chick::dizzy:
+


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!

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!

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

update 10-12

chrisgorgo · 2018-10-17T15:24:59Z

CONTRIBUTING.md

+
+## 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].


Could you point to the right .md file here?

chrisgorgo · 2018-10-17T15:26:38Z

CONTRIBUTING.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


Was this intended to be empty? We can remove it for now or add a section about opening issue to raise discussion topics.

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.

mailing list

neurostars

github

right?

chrisgorgo · 2018-10-17T15:28:52Z

CONTRIBUTING.md

+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


I don't think this should be pointing to BIDS Starter Kit.

chrisgorgo · 2018-10-17T15:29:15Z

CONTRIBUTING.md

+
+#### 2. [Fork][github-fork] the [BIDS Starter Kit repository][bids-starterkit-repo] to your profile
+
+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!


chrisgorgo · 2018-10-17T15:29:58Z

I noticed that there is a lot of square bracket syntax that is not compatible with markdown - for example [merge conflicts][github-mergeconflicts]. What's up with that?

emdupre · 2018-10-17T19:05:46Z

The square bracket convention will work with markdown if you specify the links at the end of the file (similar to RST links). So something like

[link_pullrequest]: https://help.github.com/articles/creating-a-pull-request/
[link_fork]: https://help.github.com/articles/fork-a-repo/
[link_pushpullblog]: https://www.igvita.com/2011/12/19/dont-push-your-pull-requests/

will work. But I don't see those links in this PR, unless I'm just overlooking them ?

franklin-feingold · 2018-10-17T21:09:53Z

I went through and cleaned up the double brackets, edited the sections pointing to the starter kit, added some information about linter and CI, and made sure there were no linter errors. I submitted a PR to Patrick's fork - patrick-g-h#1

KirstieJane · 2018-10-22T12:21:59Z

Hi folks! Sorry I disappeared on you for so long! I'll go over to @Park-Patrick's fork and review there first. Ping me if there are any major questions I can help with ✨

KirstieJane · 2018-10-22T12:28:14Z

Question for anyone who's following along: do we want to ask contributors to add links at the bottom of a file (using the square bracket notation that @emdupre described above #44 (comment)) or do you think it's cleaner to have each link at the time it's used?

What I like about the square brackets is that you a) don't have to re-type the same link multiple times, and b) you build up a little "useful links" section at the end of every file.

The problem though is that the link is not next to the text that you're linking in the raw markdown and so it might be rather confusing!

Add a little 🎉 emoji to this comment if you want to use the square bracket format or a ❤️ emoji if you'd prefer the [text](link) format ✨

updated contributing guide

yarikoptic · 2018-10-24T18:58:42Z

I found this PR and hoped that it would explain to how actually "build" the specification document from the src/ markdown files, but there is nothing mentioned about remark which is I guess what is used for that?

chrisgorgo · 2018-10-24T19:01:57Z

Indeed it would be good to add those instructions to this document. I just added CI integration to build docs for all commits. You can learn what commands are required from the config file: https://github.com/bids-standard/bids-specification/blob/master/.circleci/config.yml

update 10/24

franklin-feingold · 2018-10-24T23:37:54Z

Thank you for bring this up @yarikoptic! I have just added a short tutorial of how to build the specification locally using mkdocs. I submitted a PR to @Park-Patrick's repository.

chrisgorgo · 2018-10-25T17:23:54Z

@Park-Patrick what's the ETA on this PR? If you are busy perhaps @franklin-feingold or @KirstieJane could take over?

Added to contributing guide - mkdocs tutorial

patrick-g-h · 2018-10-26T13:23:18Z

Okay just merged @franklin-feingold 's most recent PR! Sorry, I thought it was the same one that I merged a few days ago.
Also hate to cause any delays on this. I don't mind keeping up/merging but if there's any way for me to give other people a way to keep things moving that works too!

chrisgorgo · 2018-10-31T18:08:15Z

Thanks everyone!

pull of common elements from starter kit + some edits

999b897

patrick-g-h mentioned this pull request Oct 11, 2018

add CONTRIBUTING.md with links/specs of style guide #11

Closed

KirstieJane reviewed Oct 11, 2018

View reviewed changes

franklin-feingold reviewed Oct 12, 2018

View reviewed changes

patrick-g-h changed the title ~~pull of common elements from starter kit + some edits~~ edit contributing md Oct 12, 2018

patrick-g-h and others added 4 commits October 12, 2018 04:00

Update CONTRIBUTING.md

6c8c073

Update CONTRIBUTING.md

3bdca0c

Merge pull request bids-standard#3 from bids-standard/master

1f6f59e

update 10-12

Update CONTRIBUTING.md

0a5654f

chrisgorgo reviewed Oct 17, 2018

View reviewed changes

patrick-g-h added 2 commits October 22, 2018 09:36

Merge branch 'patch-1' into master

36b8caa

Merge pull request #1 from franklin-feingold/master

eb113fb

updated contributing guide

franklin-feingold added 2 commits October 24, 2018 23:12

Merge pull request bids-standard#4 from bids-standard/master

d99e4fa

update 10/24

Add files via upload

63c245a

franklin-feingold added 2 commits October 24, 2018 16:52

Small edit

184b868

Small edit

98cd127

Merge pull request #2 from franklin-feingold/master

65a2095

Added to contributing guide - mkdocs tutorial

teonbrooks mentioned this pull request Oct 31, 2018

[MISC] Added appendix to mkdocs and added some internal links #77

Merged

chrisgorgo merged commit 1bc8c1e into bids-standard:master Oct 31, 2018

sappelhoff changed the title ~~edit contributing md~~ [MISC] edit contributing guide Sep 8, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[MISC] edit contributing guide #44

[MISC] edit contributing guide #44

patrick-g-h commented Oct 11, 2018

KirstieJane left a comment

KirstieJane Oct 11, 2018

patrick-g-h Oct 12, 2018

KirstieJane Oct 11, 2018

patrick-g-h Oct 12, 2018

emdupre Oct 12, 2018

KirstieJane commented Oct 11, 2018

franklin-feingold Oct 12, 2018

patrick-g-h Oct 12, 2018

franklin-feingold Oct 12, 2018

chrisgorgo Oct 17, 2018

chrisgorgo Oct 17, 2018

KirstieJane Oct 22, 2018

chrisgorgo Oct 17, 2018

chrisgorgo Oct 17, 2018

chrisgorgo commented Oct 17, 2018

emdupre commented Oct 17, 2018

franklin-feingold commented Oct 17, 2018

KirstieJane commented Oct 22, 2018

KirstieJane commented Oct 22, 2018

yarikoptic commented Oct 24, 2018

chrisgorgo commented Oct 24, 2018

franklin-feingold commented Oct 24, 2018

chrisgorgo commented Oct 25, 2018

patrick-g-h commented Oct 26, 2018

chrisgorgo commented Oct 31, 2018

		:tada::balloon::cake: Welcome to the BIDS Specification repository! :cake::balloon::tada:

		:dizzy::hatched_chick::sunny: We're so excited you're here and want to contribute. :sunny::hatched_chick::dizzy:


		## 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].


		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

		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


		#### 2. [Fork][github-fork] the [BIDS Starter Kit repository][bids-starterkit-repo] to your profile

		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!

[MISC] edit contributing guide #44

[MISC] edit contributing guide #44

Conversation

patrick-g-h commented Oct 11, 2018

KirstieJane left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

KirstieJane commented Oct 11, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisgorgo commented Oct 17, 2018

emdupre commented Oct 17, 2018

franklin-feingold commented Oct 17, 2018

KirstieJane commented Oct 22, 2018

KirstieJane commented Oct 22, 2018

yarikoptic commented Oct 24, 2018

chrisgorgo commented Oct 24, 2018

franklin-feingold commented Oct 24, 2018

chrisgorgo commented Oct 25, 2018

patrick-g-h commented Oct 26, 2018

chrisgorgo commented Oct 31, 2018