Some updates for the contributing file. #1705

fables-tales · 2016-09-28T08:56:25Z

No description provided.

JonRowe

Great! Remind me is rspec-rails seperate on our file management here? The others are all managed from rspec-dev...

JonRowe · 2016-09-28T09:19:34Z

CONTRIBUTING.md

+
+## `Small` issues
+
+Small issues are the ones that we be believe are best suited for new


Personally I feel these lines would read better as These issues ... as its a bit repetitious at the moment.

JonRowe · 2016-09-28T09:20:10Z

CONTRIBUTING.md

+
+Small issues are the ones that we be believe are best suited for new
+contributors to get started on. They represent a meaningful contribution to the
+project that can be made that should not be too hard to pull off.


This reads a bit funny to me, how about They represent a potential meaningful contribution to the project that should not be too hard to pull off.

JonRowe · 2016-09-28T09:20:46Z

CONTRIBUTING.md

+## `Triage` issues
+
+Triage issues are ones that have been labelled by the maintainers that we
+believe do not currently have enough information for them to be reproduced by


Suggestion: currently have enough information to be reproduced by

JonRowe · 2016-09-28T09:21:51Z

CONTRIBUTING.md

+
+Issues that have reproduction cases have a repository that we can clone that
+enable us to quickly determine the issue is valid and then start debugging
+within RSpec. These issues are good ones to tackle to help us actively fix bugs.


Do we do this on other repos?

I've been doing this on RR for a while, not sure about the other repos.

The interactions between rspec and rails in rspec-rails and subtle enough that having a clonable repo is pretty important here. For the other repos, it's much less so; often times the description from the user is sufficient, or a snippet from them. Sometimes we can't reproduce and do ask for a repo.

myronmarston · 2016-09-28T16:15:38Z

We might consider creating an Issue template. For example, here's Elixir's:

https://github.com/elixir-lang/elixir/blob/master/ISSUE_TEMPLATE.md

You can see how this looks when you create a new issue:

https://github.com/elixir-lang/elixir/issues/new

Thoughts?

fables-tales · 2016-09-28T16:48:00Z

@myronmarston would you propose that instead of these changes, or as an additional step?

myronmarston · 2016-09-28T16:50:57Z

In addition to. The changes here are fine, but I think it would make for fewer issues where we have to ask the user for more details if we give them a template to fill out that provides the details we need.

fables-tales · 2016-11-19T15:04:52Z

@JonRowe @myronmarston I've made some edits to contributing.md and added an issue template. Can I get another review pass?

myronmarston

Left a few comments, but I don't consider them merge blockers.

myronmarston · 2016-11-19T17:00:10Z

CONTRIBUTING.md

+These issues are the ones that we be believe are best suited for new
+contributors to get started on. They represent a potential meaningful
+contribution to the project that should not be too hard to pull off.
+## `Triage` issues


There should be a line break between the paragraph and the next section header.

myronmarston · 2016-11-19T17:01:41Z

CONTRIBUTING.md

+These issues are ones that have been labelled by the maintainers that we
+believe do not currently have enough information to be reproduced the RSpec
+team. You can help us move triage issues into `ready to go` or `has reproduction
+case` (for feature requests or bugs) as a seriously meaningful contribution.


The way this sentence is worded, it sounds like people can help us by changing the issue label. I think it would be better to state what is needed to get a triaged issue into one of these states.

myronmarston · 2016-11-19T17:02:55Z

CONTRIBUTING.md

+
+Issues that have reproduction cases have a repository that we can clone that
+enable us to quickly determine the issue is valid and then start debugging
+within RSpec. These issues are good ones to tackle to help us actively fix bugs.


The interactions between rspec and rails in rspec-rails and subtle enough that having a clonable repo is pretty important here. For the other repos, it's much less so; often times the description from the user is sufficient, or a snippet from them. Sometimes we can't reproduce and do ask for a repo.

myronmarston · 2016-11-19T17:04:51Z

ISSUE_TEMPLATE.md

+follow. If you can't do all of these, don't worry, but if you can it'll help us
+resolve your bug faster!
+
+-->


Is the idea of the HTML comments that it won't render on the github UI if they are left in place?

myronmarston · 2016-11-19T17:09:50Z

ISSUE_TEMPLATE.md

+
+-->
+
+## Description of issue


I think instead of the description of the issue, we should ask for observed behavior and expected behavior. Often times we get issues where users describe the problem, but the behavior is what we would expect. Then we have to go back and forth with the user to get them to explain what about the behavior was unexpected. Asking for them to explain observed vs expected behavior up front will hep, I think.

ashleygwilliams

overall this looks good! a few things on naming and rewording questions to optimize for end user success

ashleygwilliams · 2016-11-20T18:31:27Z

CONTRIBUTING.md

@@ -23,3 +23,29 @@ If you'd like to help make RSpec better, here are some ways you can contribute:
 If you need help getting started, check out the [DEVELOPMENT](DEVELOPMENT.md) file for steps that will get you up and running.

 Thanks for helping us make RSpec better!
+
+## `Small` issues


i would use literally anything other than small. 2 reasons:

downplays the effort of new contributors

doesn't properly signal that these issues should be reserved for new contributors

recommendations: your-first-PR, starter-issue

i would also recommend a PRs welcome tag that flags that PRs are welcome, and then put another tag alongside it that flags that it would be good for a new contributor

another consideration: when you talk about "first" issues, do you mean first contribution to the rspec collection of software, OR first contribution ever? this will inform the name of the tag you use as well as the amount of scaffolding that you'll need to provide in the issue.

ashleygwilliams · 2016-11-20T18:32:12Z

CONTRIBUTING.md

+
+These issues are the ones that we be believe are best suited for new
+contributors to get started on. They represent a potential meaningful
+contribution to the project that should not be too hard to pull off.


i would considered adding/reframing this text based on how you answer the above issues/questions

ashleygwilliams · 2016-11-20T18:33:14Z

CONTRIBUTING.md

+contributors to get started on. They represent a potential meaningful
+contribution to the project that should not be too hard to pull off.
+
+## `Triage` issues


maybe this should be "need reproduction"- triage is a label i've seen on many repos as triaged which flags that it has already been triaged, and as a result may have the opposite effect.

ashleygwilliams · 2016-11-20T18:34:08Z

CONTRIBUTING.md

+believe do not currently have enough information to be reproduced the RSpec
+team. While not directly counted by the GitHub contribution graph, we consider
+helping us triage issues to the point where they can be reproduced as an
+extremely meaningful contribution.


you might add classic "how to triage" advice, e.g. what versions of X, Y, Z.

ah, based on the subsequent section it sounds like you want a repo with a repro case in it for this. you should say that!

ashleygwilliams · 2016-11-20T18:35:55Z

CONTRIBUTING.md

+enable us to quickly determine the issue is valid and then start debugging
+within RSpec. These issues are good ones to tackle to help us actively fix bugs.
+
+## Maintenance branches


this seems very different than the previous sections, you might consider putting this is a different section. it is a not a issue label so perhaps "dev env" or something like this is a better move. either way i'd get it out of this section.

ashleygwilliams · 2016-11-20T18:36:58Z

ISSUE_TEMPLATE.md

+
+-->
+
+## Observed behaviour


before this question, you should ask "what were you trying to do"-

ashleygwilliams · 2016-11-20T18:37:15Z

ISSUE_TEMPLATE.md

+differs from the current behaviour.
+-->
+
+## Can you provide an example app?


you want a link, so you should say link...

Isn't mention on line 45?

ashleygwilliams · 2016-11-20T18:37:52Z

ISSUE_TEMPLATE.md

+5. Provide a link to a github repo, a description of the app and what you're expecting here
+-->
+
+## What Ruby, Rails and RSpec versions are you using?


honestly i'd put this as the very first question and i'd consider making it 3 separate questions. people don't read and will only answer this partially which will be a bummer

ashleygwilliams · 2016-11-20T18:38:22Z

ISSUE_TEMPLATE.md

+
+-->
+
+## Did this problem exist before you upgraded to Rails 5?


you could put checkboxes or radio boxes for yes/no here

if you want a freeform answer you might widen this to "did you notice this bug after a specific update or event? please explain. e.g. updated to rails 5"

JonRowe reviewed Sep 28, 2016

View reviewed changes

JonRowe mentioned this pull request Sep 28, 2016

Updates from rspec-dev (2016-09-28) #1706

Closed

Some updates for the contributing file.

f4e41b5

fables-tales force-pushed the contributing-updates branch from 6e0963e to f4e41b5 Compare October 30, 2016 17:56

Sam Phippen added 2 commits November 19, 2016 10:03

Make some further edits to contributing.md

142dd9c

Add an issue template.

643fa20

myronmarston approved these changes Nov 19, 2016

View reviewed changes

Make some edits to contributing and issue template.

8ed95b3

ashleygwilliams suggested changes Nov 20, 2016

View reviewed changes

benoittgt added a commit to benoittgt/rspec-rails that referenced this pull request Dec 9, 2017

Implement comments review from Ashley on rspec#1705

f670ea4

benoittgt added a commit to benoittgt/rspec-rails that referenced this pull request Dec 9, 2017

Implement comments review from Ashley on rspec#1705

dbceca2

benoittgt mentioned this pull request Dec 9, 2017

Contributing updates v2 #1925

Merged

JonRowe merged commit 8ed95b3 into master Apr 24, 2018

sebjacobs pushed a commit to futurelearn/rspec-rails that referenced this pull request Mar 15, 2019

Implement comments review from Ashley on rspec#1705

af211e7

pirj deleted the contributing-updates branch March 12, 2020 09:44


		## `Small` issues

		Small issues are the ones that we be believe are best suited for new


		-->

		## Did this problem exist before you upgraded to Rails 5?

Uh oh!

Some updates for the contributing file. #1705

Some updates for the contributing file. #1705

Uh oh!

Conversation

fables-tales commented Sep 28, 2016

Uh oh!

JonRowe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

myronmarston commented Sep 28, 2016

Uh oh!

fables-tales commented Sep 28, 2016

Uh oh!

myronmarston commented Sep 28, 2016

Uh oh!

fables-tales commented Nov 19, 2016

Uh oh!

myronmarston left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ashleygwilliams left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!