Skip to content

Commit

Permalink
Make GitHub templates more concise
Browse files Browse the repository at this point in the history
  • Loading branch information
@remear
remear committed Feb 26, 2016
1 parent 5517ab8 commit 81ad437
Show file tree
Hide file tree
Showing 3 changed files with 57 additions and 165 deletions.
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Integrated application and version *(e.g., Rails, Grape, etc)*:
<br><br>

#### Backtrace
*(e.g., provide any applicable backtraces from your application)
*(e.g., provide any applicable backtraces from your application)*
<br><br><br>

#### Additonal helpful information
Expand Down
24 changes: 10 additions & 14 deletions .github/PULL_REQUEST_TEMPLATE.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,14 @@
### Links to any relevant github issues:
#### Purpose
<br><br>

- [Issue description](http://example.com/org/repo/issues/411). Any other useful information.
#### Changes
<br><br>

### What's in the the PR
#### Caveats
<br><br>

- [ ] A description of the changes proposed in the pull request.
- [ ] Any areas or issues reviewer should pay attention to? (comments in diff okay).
- [ ] Update `/docs` to include, whenever possible, a new, suitable recommendation about how to use
the feature.
- [ ] Extra Credit: [Confirm it runs and tests pass on the Rubies specified in the Travis
config](.travis.yml). A maintainer will otherwise confirm it runs on these.
- [ ] *Bonus Points* Update [CHANGELOG.md](https://github.com/rails-api/active_model_serializers/blob/master/CHANGELOG.md)
with a brief description of any breaking changes, fixes, features, or
miscellaneous changes at the top of the proper version section.
#### Related GitHub issues
<br><br>

For more general information, see [Submitting a pull request](
https://github.com/rails-api/active_model_serializers/blob/master/CONTRIBUTING.md#submitting-a-pull-request-pr).
#### Additonal helpful information
<br><br>
196 changes: 46 additions & 150 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,158 +1,71 @@
First of all, **thank you**!
## Have an issue?

![Commit Strip
http://www.commitstrip.com/en/2014/05/07/the-truth-behind-open-source-apps/](docs/how-open-source-maintained.jpg)
Before opening an issue, try the following:

## Common issues and resolutions
##### Consult the documentation

- Using `grape-active_model_serializers`, or any non-Rails server. See
[issue](https://github.com/rails-api/active_model_serializers/issues/1258).
See if your issue can be resolved by information in the
[documentation](https://github.com/rails-api/active_model_serializers/tree/master/docs).

## How can I help?
##### Check for an existing issue

- [Filing an issue](CONTRIBUTING.md#filing-an-issue)
- [Writing code and comments](CONTRIBUTING.md#writing-code-and-comments)
Take a look at the issues to see if a similar one has already been created. If
one exists, please add any additional information that might expedite
resolution.

### Filing an issue
#### Open an issue

Everyone is encouraged to open issues that are affecting them:
bugs, ideas, documentation (`/docs`), performance problems – everything helps!
If the documentation wasn't able to help resolve the issue and no issue already
exists, please open a new issue with the following in mind:

#### Before
- Please make sure only to include one issue per report. If you encounter
multiple, unrelated issues, please report them as such.
- Be detailed. Provide backtraces and example code when possible. Provide
information about your environment. e.g., Ruby version, rails version, etc.
- Own your issue. Actively participate in the discussion and help drive the
issue to closure.
- If you resolve your own issue, please share the details on the issue and close
it out. Others might have the same issue and sharing solutions is helpful.

1. Start by looking at our [GitHub Issues](https://github.com/rails-api/active_model_serializers/issues).
## Contributing

- Check if your issue has already been reported.
- If you find an existing issue report, feel free to add further information to that report.
Contributing can be done in many ways and is not exclusive to code. If you have
thoughts on a particular issue or feature, we encourage you to open new issues
for discussion or add your comments to existing ones.

#### Writing
#### Pull requests

If possible, please include the following information when [reporting an
issue](https://github.com/rails-api/active_model_serializers/issues/new):
We also gladly welcome pull requests. When preparing to work on pull request,
please adhere to these standards:

- Ruby version: `ruby -e "puts RUBY_DESCRIPTION"`.
- Steps to reproduce the issue (i.e. "Show me how to show myself." ). What did you expect to
happen? What happened? What did you try?
- Include as much sample code as you can to help us reproduce the issue.
(Inline, repo link, or gist, are fine. A failing test would help the most.)
This is extremely important for narrowing down the cause of your problem.
- Base work on the master branch
- Squash your commits and regularly rebase off master.
- Provide a description of the changes contained in the pull request.
- Note any specific areas that should be reviewed.
- Include tests.
- The test suite must pass on [supported Ruby versions](.travis.yml)
- Include updates to the [documentation](https://github.com/rails-api/active_model_serializers/tree/master/docs) where applicable.
- Update the
[CHANGELOG](https://github.com/rails-api/active_model_serializers/blob/master/CHANGELOG.md)
to the appropriate sections with a brief description of the changes.
- Do not change the VERSION file.

Please make sure only to include one issue per report.
If you encounter multiple, unrelated issues, please report them as such.
#### Running tests

Simon Tatham has written an excellent on article on
[How to Report Bugs Effectively](http://www.chiark.greenend.org.uk/~sgtatham/bugs.html)
which is [well worth reading](http://yourbugreportneedsmore.info/), although it is not specific to ActiveModelSerializers.
Run all tests

Thanks!
`$ rake test`

#### After
Run a single test suite

Thanks to everyone involved!

Sometimes an issue will be closed by a maintainer for various reasons. In some cases, this is
an invitation to make a better case for your issue or be able to reproduce a bug, and
its being closed is just an opportunity to help out some more, and then re-open.

If you get help, sharing it back in the form of a pull-request or making an issue to document
what you've found is *extremely* helpful.

If you solve your issue, stop working on it, or realize the problem was something else,
please share that in a comment to an issue and close it. That way, everyone can learn and
we don't have closed issues without a clear resolution. Even if it's just a stackoverflow link :)
And please don't forget to stay involved in the issue until it is closed! Thanks to all!

### Writing code and comments

- We are actively working to identify tasks under the label [**Good for New
Contributors**](https://github.com/rails-api/active_model_serializers/labels/Good%20for%20New%20Contributors).
- [Changelog
Missing](https://github.com/rails-api/active_model_serializers/issues?q=label%3A%22Changelog+Missing%22+is%3Aclosed) is
an easy way to help out.

- [Fix a bug](https://github.com/rails-api/active_model_serializers/labels/Ready%20for%20PR).
- Ready for PR - A well defined bug, needs someone to PR a fix.
- Bug - Anything that is broken.
- Regression - A bug that did not exist in previous versions and isn't a new feature (applied in tandem with Bug).
- Performance - A performance related issue. We could track this as a bug, but usually these would have slightly lower priority than standard bugs.

- [Develop new features](https://github.com/rails-api/active_model_serializers/labels/Feature).

- [Improve code quality](https://codeclimate.com/github/rails-api/active_model_serializers/code?sort=smell_count&sort_direction=desc).

- [Improve amount of code exercised by tests](https://codeclimate.com/github/rails-api/active_model_serializers/coverage?sort=covered_percent&sort_direction=asc).

- [Fix RuboCop (Style) TODOS](https://github.com/rails-api/active_model_serializers/blob/master/.rubocop_todo.yml).
- Delete and offsense, run `rake rubocop` (or possibly `rake rubocop:auto_correct`),
and [submit a PR](CONTRIBUTING.md#submitting-a-pull-request-pr).

- We are also encouraging comments to substantial changes (larger than bugfixes and simple features) under an
"RFC" (Request for Comments) process before we start active development.
Look for the [**RFC**](https://github.com/rails-api/active_model_serializers/labels/RFC) label.

#### Submitting a pull request (PR)

1. The vast majority of development is happening under the `master` branch.
This is where we would suggest you start.
1. Fixing bugs is extraordinarily helpful and requires the least familiarity with ActiveModelSerializers.
Look for issues labeled [**Needs Bug Verification**](https://github.com/rails-api/active_model_serializers/labels/Needs%20Bug%20Verification) and [**Bug**](https://github.com/rails-api/active_model_serializers/labels/bug).
1. Adding or fixing documentation is also fantastic!

To fetch & test the library for development, do:

1. Fork the repository ( https://github.com/rails-api/active_model_serializers/fork )
1. `git clone https://github.com/{whoami}/active_model_serializers.git`
1. `cd active_model_serializers`
1. `bundle`
- To test against a particular rails version-- 4.0 is usually the most buggy-- set then
RAILS_VERSION environment variable as described in the [.travis.yml](.travis.yml).
e.g. `export RAILS_VERSION=4.0`.
1. Create your PR branch (`git checkout -b my-helpful-pr`)
1. Write tests for your feature, or regression tests highlighting a bug.
This is important so ActiveModelSerializers doesn't break it in a future version unintentionally.
1. Write the feature itself, or fix your bug
1. `bundle exec rake`
1. Commit your changes (`git commit -am 'Add some feature'`)
- Use well-described, small (atomic) commits.
1. Push to the branch (`git push origin my-helpful-pr`)
1. Create a new Pull Request
- *Don't* change the VERSION file.
1. Iterate on feedback given by the community (fix syntax, modify bits of code, add
tests), pushing the new commits to the PR each time

Remember to [squash your commits](CONTRIBUTING.md#about-pull-requests-prs) and rebase off `master`.

#### How maintainers handle pull requests:

- If the tests pass and the pull request looks good, a maintainer will merge it.
- If the pull request needs to be changed,
- you can change it by updating the branch you generated the pull request from
- either by adding more commits, or
- by force pushing to it
- A maintainer can make any changes themselves and manually merge the code in.

#### Commit Messages

- [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
- [http://stopwritingramblingcommitmessages.com/](http://stopwritingramblingcommitmessages.com/)
- [ThoughtBot style guide](https://github.com/thoughtbot/guides/tree/master/style#git)

#### About Pull Requests (PR's)

- [Using Pull Requests](https://help.github.com/articles/using-pull-requests)
- [Github pull requests made easy](http://www.element84.com/github-pull-requests-made-easy.html)
- [Exercism Git Workflow](http://help.exercism.io/git-workflow.html).
- [Level up your Git](http://rakeroutes.com/blog/deliberate-git/)
- [All Your Open Source Code Are Belong To Us](http://www.benjaminfleischer.com/2013/07/30/all-your-open-source-code-are-belong-to-us/)

## Issue Labeling
`$ rake test TEST=path/to/test.rb`

ActiveModelSerializers uses a subset of [StandardIssueLabels](https://github.com/wagenet/StandardIssueLabels) for Github Issues. You can [see our labels here](https://github.com/rails-api/active_model_serializers/labels).
Run a single test

## Running tests
`$ rake test TEST=path/to/test.rb TESTOPTS="--name=test_something"`

Run tests against different Rails versions by setting the RAILS_VERSION variable
and bundling gems. To test against all versions, you can do something like:
and bundling gems.

```bash
for version in 4.0 4.1 4.2 master; do
Expand All @@ -171,20 +84,3 @@ for version in 4.0 4.1 4.2 master; do
done
```

### Running with Rake

The easiest way to run the unit tests is through Rake. The default task runs
the entire test suite for all classes. For more information, checkout the
full array of rake tasks with "rake -T"

Rake can be found at http://docs.seattlerb.org/rake/.

To run a single test suite

`$ rake test TEST=path/to/test.rb`

Which can be further narrowed down to one test:

`$ rake test TEST=path/to/test.rb TESTOPTS="--name=test_something"`

:heart: :sparkling_heart: :heart:

0 comments on commit 81ad437

Please sign in to comment.