Skip to content

Some updates for the contributing file. #1705

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Apr 24, 2018
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


## `Triage` issues
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!


## `Has reproduction case` issues

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we do this on other repos?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


## Maintenance branches

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


Maintenance branches are how we manage the different supported point releases
of RSpec. As such, while they might look like good candidates to merge into
master, please do not open pull requests to merge them.
67 changes: 67 additions & 0 deletions ISSUE_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
<!--

Hi there! Here's a few pointers to help us help you with your issue as quickly
as possible.

We prefer that the RSpec Rails issue tracker be mainly used for bug reports.
Feature requests or general requests for help should go to our google group:
[email protected]. We use that as our primary location for higher level
RSpec discussions.

If you are filing a bug report, there's a few steps it'd be super if you could
follow. If you can't do all of these, don't worry, but if you can it'll help us
resolve your bug faster!

-->
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes


## Observed behaviour

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


<!--
please provide a concise description of the behaviour you are observing with
RSpec and Rails
-->

## Expected behaviour

<!--
Please provide a description of what you expect to be happening, and how that
differs from the current behaviour.
-->

## Can you provide an example app?

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't mention on line 45?


<!--
This step is probably the most important in allowing us to quickly debug
your issue, and we typically ask that you follow these steps:

1. `rails new` an app at the specific version of ruby and rails that you are
using
2. commit that app, so that we have the rails skeleton in a separate commit
3. Make all the changes necessary (adding RSpec, models, specs, controllers,
etc) to reproduce the issue. There should be a failing test or tests that you
expect to pass. We'll run `bundle exec rspec`, but if you can provide a
readme with more detailed instructions that'd be amazing :)
4. Commit
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?

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


<!--

You can run

```
bundle exec ruby --version
bundle exec rails --version
bundle exec rspec --version
```

and paste the output below

-->

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"


<!-- We're still tracking down a few edge cases since Rails 5 came out, so if
it's new for you since Rails 5, that'll help us find it faster -->