[ENH] Update contributing guide and README to make discussion forums easy to find #279

emdupre · 2019-07-20T19:18:26Z

For consideration to update text in the README and CONTRIBUTING documents.

Related to #273, #275.

Pinging @franklin-feingold @sappelhoff @effigies based on previous conversations, but all feedback is welcome !

Rendered README.
Rendered CONTRIBUTING.

sappelhoff

Thanks! I think this is a great improvement and still taking into account Franklin's and my points in #273 and #275

While we are at it, could we perhaps delete the following lines from the CONTRIBUTING.md?

The "We're so excited you're here and want to contribute." at the beginning
The "Thank you!" and "You're awsome" at the end

I think these are slightly distracting :-)

effigies

I would say this looks good. A couple small comments.

effigies · 2019-07-22T15:23:41Z

CONTRIBUTING.md


 ## Contributing through GitHub

-[Git](https://git-scm.com/) is a really useful tool for version control. [GitHub](https://github.com/) sits on top of git and supports collaborative and distributed working.
+[git](https://git-scm.com/) is a really useful tool for version control. [GitHub](https://github.com/) sits on top of git and supports collaborative and distributed working.


I don't know if there's an MLA convention or something, but I would capitalize at the beginning of a sentence, unless using backticks to indicate that we're referring specifically to the CLI git.

effigies · 2019-07-22T15:30:57Z

README.md

+When you're ready to get started, check out [our contributing guidelines](https://github.com/bids-standard/bids-specification/blob/master/CONTRIBUTING.md).
+
+Want to learn more about working with BIDS? Have a question, comment, or suggestion?
+Open or comment on one of our [NeuroStars issues](https://neurostars.org/tags/bids)!


This feels a little out of place in the "Contributing section" and might be skipped over by a new user that doesn't consider themselves an aspiring contributor. Perhaps it would be better to place it as the lat thing before the sub-section?

Moved and added mention of the Starter Kit based on a previous comment from @franklin-feingold

emdupre · 2019-07-22T16:18:40Z

Thanks for the feedback, @sappelhoff and @effigies !

Re :

While we are at it, could we perhaps delete the following lines from the CONTRIBUTING.md?

The "We're so excited you're here and want to contribute." at the beginning

The "Thank you!" and "You're awsome" at the end

Personally I quite like the intro-outro, but I'm happy to be outvoted if you feel strongly.

README.md

franklin-feingold · 2019-07-22T21:49:37Z

README.md

@@ -1,13 +1,28 @@
 [![Build Status](https://travis-ci.com/bids-standard/bids-specification.svg?branch=master)](https://travis-ci.com/bids-standard/bids-specification)
 [![CircleCI](https://circleci.com/gh/bids-standard/bids-specification.svg?style=svg)](https://circleci.com/gh/bids-standard/bids-specification)



adding the twitter badge in

Suggested change

[![@BIDSstandard](http://img.shields.io/twitter/follow/bidsstandard.svg?style=social)](https://twitter.com/BIDSstandard)

appears #268 takes care of adding the badge. added this to ensure the version consistency

I won't commit this suggestion, then, so I don't create a merge conflict ! Let me know if I'm misunderstanding.

We can keep this hear in case it is needed. It depends on the order of merging since we have a number of PRs open with differing versions of text. I may be mistaken too.

I imagine #268 will merge first since I have zero approving reviews (having successfully dismissed my previous two 😅 ). I'll just merge in master if something breaks when it's merged !

Sounds good!

I'll just merge in master if something breaks when it's merged !

yep, that's the way to go :-) (or even better: git rebase master from your branch, because then we won't have a "merge commit" --> these are often making the history a bit dirty I find)

one caveat though is this will cause the changelog to go out of sync (until a merge commit is seen then it will catch up). the merge commit message is the signal for the changelog generator to generate

I went ahead and merged #268, if you want to merge/rebase, @emdupre. Though it's not obvious that it won't merge cleanly as is. GitHub isn't indicating a merge conflict, but I can't remember if it does that before all reviews are in.

franklin-feingold · 2019-07-22T21:51:30Z

I think this looks great! Thank you @emdupre for putting this together!

Personally I quite like the intro-outro, but I'm happy to be outvoted if you feel strongly.

+1, I like it too. I think it helps with the community aspect of the document

Co-Authored-By: Franklin Feingold <35307458+franklin-feingold@users.noreply.github.com>

sappelhoff · 2019-07-23T09:01:17Z

Personally I quite like the intro-outro, but I'm happy to be outvoted if you feel strongly.

yes I think this is really a question of taste, perhaps we can find a middle ground?

"Being excited" sounds a bit over the top to me, I would prefer a simple "Welcome to the BIDS contributing guide!" over the We're so excited you're here and want to contribute.
I think we should drop the Thank you! because it's not necessary to thank people for reading something they are interested in - I think that saying thanks is very important (e.g. in a discussion, or for contributions), but it's also easy to overdo it and thus "dilute the impact"
I would drop the "You're awesome" because:
1. I don't know if the reader is awesome or not
2. We are writing a contributing guide, not a pep talk :-)

If we want something to "round off" the contributing guide, how would you feel about We are looking forward to your contributions!

effigies

I'm extremely neutral on the bubbly intro/outro, so I am approving based on the current modifications.

franklin-feingold · 2019-07-24T00:24:01Z

"Being excited" sounds a bit over the top to me, I would prefer a simple "Welcome to the BIDS contributing guide!" over the We're so excited you're here and want to contribute.

To clarify - the proposal would remove

"Welcome to the BIDS Specification repository!

We're so excited you're here and want to contribute."

and replace with "Welcome to the BIDS contributing guide!" ?

I think we should drop the Thank you! because it's not necessary to thank people for reading something they are interested in - I think that saying thanks is very important (e.g. in a discussion, or for contributions), but it's also easy to overdo it and thus "dilute the impact"

We can thank those that are interested and made it through the contributing guide. I understand not wanting to overdo on thank yous, but this helps create the warm and welcoming community we want to support and grow.

I would drop the "You're awesome" because:
I don't know if the reader is awesome or not
We are writing a contributing guide, not a pep talk :-)

The contributing guide can be a pep talk to help those get to the contributing stage. Contributing can be a stressful time and relieving those concerns is important to open the way for the first contribution and many more. IMO if you are a contributor or want to I think you are awesome :)

With that being said and finding a middle ground - I can agree with second point. On the first and third point, I think starting and ending the document with something warm and friendly is really good and gives way to positive community building. As you said, this is a discussion and question of taste.

sappelhoff · 2019-07-24T07:54:56Z

Okay, let's hear what @emdupre has to say about this. I would be fine with a middle ground 👍

emdupre · 2019-07-25T15:29:17Z

What about having the intro as:

Welcome to the BIDS contributing guide!
We look forward to your contributions, and we hope that these guidelines make it as easy as possible to get involved.

And the outro as:

Thank you for contributing!

effigies · 2019-07-25T15:44:36Z

I think those are fine...

That said, I'm a little weirded out by the dynamic here, where improving the accessibility of information has become a minor conflict over the tone of text that's not actually within the suggested changes. If we do want to change it, I'm coming to feel like it should be a separate discussion.

People who saw this PR initially will have made an impression of what it addresses, which is overall more content than tone, and decided whether they want to weigh in. By expanding the scope, we're bypassing that informal process on a tone change that people might have strong opinions on, even if they didn't have strong opinions here.

sappelhoff · 2019-07-25T16:22:30Z

I also think the suggestion is good @emdupre

And I agree with @effigies that this has gotten a bit out of hand ... that was not my intent when I started this in #279 (review)

Sorry :-)

effigies · 2019-07-25T16:24:56Z

@sappelhoff I suggest that we merge this, since the existing changes here seem uncontroversial.

Then, if you like you can open a PR with the suggested tone changes, and we can have that discussion, there?

sappelhoff · 2019-07-25T16:25:25Z

Agreed

franklin-feingold · 2019-07-25T16:42:48Z

I agree with @emdupre changes. Agree and I'm sorry that this has progressed to this point. I agree with a separate thread/PR to discuss tone

enh: update readme, contrib

531a5bf

emdupre mentioned this pull request Jul 20, 2019

[MISC] improve docs on how to contrib in README #275

Closed

emdupre added the community Issues related to building and supporting the BIDS community label Jul 20, 2019

sappelhoff previously approved these changes Jul 21, 2019

View reviewed changes

sappelhoff added this to the 1.2.1 milestone Jul 22, 2019

sappelhoff mentioned this pull request Jul 22, 2019

[ENH] Starter Kit dropdown menu #278

Merged

sappelhoff requested review from franklin-feingold and effigies July 22, 2019 15:05

effigies reviewed Jul 22, 2019

View reviewed changes

Address @effigies review

6417c1c

emdupre dismissed sappelhoff’s stale review via 6417c1c July 22, 2019 16:16

effigies previously approved these changes Jul 22, 2019

View reviewed changes

PeerHerholz mentioned this pull request Jul 22, 2019

BIDS Governance Proposal #260

Closed

franklin-feingold reviewed Jul 22, 2019

View reviewed changes

README.md Outdated Show resolved Hide resolved

franklin-feingold reviewed Jul 22, 2019

View reviewed changes

Apply suggestion to bold text

d4c36d2

Co-Authored-By: Franklin Feingold <35307458+franklin-feingold@users.noreply.github.com>

emdupre dismissed effigies’s stale review via d4c36d2 July 23, 2019 00:13

effigies approved these changes Jul 23, 2019

View reviewed changes

sappelhoff approved these changes Jul 25, 2019

View reviewed changes

effigies changed the title ~~[enh] update readme, contrib~~ [ENH] Update contributing guide and README to make discussion forums easy to find Jul 25, 2019

franklin-feingold approved these changes Jul 25, 2019

View reviewed changes

effigies merged commit 1680756 into master Jul 25, 2019

effigies deleted the enh/contrib-pathways branch July 25, 2019 16:39

franklin-feingold added a commit that referenced this pull request Jul 25, 2019

[DOC] Auto-generate changelog entry for PR #279

745c484

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[ENH] Update contributing guide and README to make discussion forums easy to find #279

[ENH] Update contributing guide and README to make discussion forums easy to find #279

emdupre commented Jul 20, 2019 •

edited

Loading

sappelhoff left a comment

effigies left a comment

effigies Jul 22, 2019

effigies Jul 22, 2019

emdupre Jul 22, 2019

emdupre commented Jul 22, 2019

franklin-feingold Jul 22, 2019

franklin-feingold Jul 22, 2019

emdupre Jul 23, 2019

franklin-feingold Jul 23, 2019

emdupre Jul 23, 2019

franklin-feingold Jul 23, 2019

sappelhoff Jul 23, 2019

franklin-feingold Jul 23, 2019

effigies Jul 25, 2019

franklin-feingold commented Jul 22, 2019 •

edited

Loading

sappelhoff commented Jul 23, 2019

effigies left a comment

franklin-feingold commented Jul 24, 2019

sappelhoff commented Jul 24, 2019

emdupre commented Jul 25, 2019

Thank you for contributing!

effigies commented Jul 25, 2019

sappelhoff commented Jul 25, 2019

effigies commented Jul 25, 2019

sappelhoff commented Jul 25, 2019

franklin-feingold commented Jul 25, 2019

		@@ -1,13 +1,28 @@
		[![Build Status](https://travis-ci.com/bids-standard/bids-specification.svg?branch=master)](https://travis-ci.com/bids-standard/bids-specification)
		[![CircleCI](https://circleci.com/gh/bids-standard/bids-specification.svg?style=svg)](https://circleci.com/gh/bids-standard/bids-specification)


	[![@BIDSstandard](http://img.shields.io/twitter/follow/bidsstandard.svg?style=social)](https://twitter.com/BIDSstandard)

[ENH] Update contributing guide and README to make discussion forums easy to find #279

[ENH] Update contributing guide and README to make discussion forums easy to find #279

Conversation

emdupre commented Jul 20, 2019 • edited Loading

sappelhoff left a comment

Choose a reason for hiding this comment

effigies 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

emdupre commented Jul 22, 2019

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

Choose a reason for hiding this comment

franklin-feingold commented Jul 22, 2019 • edited Loading

sappelhoff commented Jul 23, 2019

effigies left a comment

Choose a reason for hiding this comment

franklin-feingold commented Jul 24, 2019

sappelhoff commented Jul 24, 2019

emdupre commented Jul 25, 2019

Thank you for contributing!

effigies commented Jul 25, 2019

sappelhoff commented Jul 25, 2019

effigies commented Jul 25, 2019

sappelhoff commented Jul 25, 2019

franklin-feingold commented Jul 25, 2019

emdupre commented Jul 20, 2019 •

edited

Loading

franklin-feingold commented Jul 22, 2019 •

edited

Loading