Skip to content
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.

Sign up for GitHub

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

Add more info to CONTRIBUTING #1259

Merged
merged 4 commits into from
Oct 21, 2015
+153 −25
Merged

Add more info to CONTRIBUTING #1259

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
200625f
Add image from commit strip [ci skip]
bf4 Oct 9, 2015
285dd6d
Add more info to CONTRIBUTING [ci skip]
bf4 Oct 9, 2015
8c52c36
Edit per beauby [ci skip]
bf4 Oct 15, 2015
fcf5f8c
Edits per joaomdmoura [ci skip]
bf4 Oct 21, 2015
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
174 changes: 151 additions & 23 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,39 +1,167 @@
![Commit Strip
http://www.commitstrip.com/en/2014/05/07/the-truth-behind-open-source-apps/](docs/how-open-source-maintained.jpg)

## Common issues and resolutions

- Using `grape-active_model_serializers`, or any non-Rails server. See
Copy link
Member

Choose a reason for hiding this comment

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

👍

[issue](https://github.com/rails-api/active_model_serializers/issues/1258).

## How can I help?

Everyone is encouraged to open issues that are affecting you: bugs, ideas, performance problems – everything helps!
### Filing an issue

Everyone is encouraged to open issues that are affecting them:
bugs, ideas, documentation (`/docs`), performance problems – everything helps!

#### Before

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

- Check if your issue has already been reported.
- If you find an existing issue report, feel free to add further information to that report.


#### Writing

If possible, please include the following information when [reporting an
issue](https://github.com/rails-api/active_model_serializers/issues/new):

- ActiveModelSerializers version (0.8.x, 0.9.x, 0.10.x, commit ref).
Copy link
Member

Choose a reason for hiding this comment

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

👍

- What are you using ActiveModelSerializers with? Rails? Grape? Other? Which versions?
- If you are not running the latest version (please check), and you cannot update it,
please specify in your report why you can't update to the latest version.
- Operating system type + version.
- Ruby version with patch level. And whether you're using rvm, rbenv, etc.
- Include your ruby -e "puts RUBY_DESCRIPTION".
- Clearly-written steps to reproduce the issue (i.e. "Show me how to show myself." ), including:
Copy link
Contributor

Choose a reason for hiding this comment

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

Maybe state that:

  • best case, provide a failing test
  • if you can't, provide a github repo with a minimal project exhibiting the behavior
  • if you can't, then provide steps to reproduce

Copy link
Member Author

Choose a reason for hiding this comment

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

addressed

- What were you doing? Include code if possible.
- Command line parameters used, if any.
- RubyGems code in your Gemfile, if any. Gemfile.lock, if possible.
- Any configuration you've made.
- What did you expect to happen?
- What happened? Include as much information as possible.
- Nature of reported defect (e.g. user name missing, not "It doesn't work."). Is it intermittent?
- The best help here is a failing test. Even better if it's a PR.
- Then the steps to reproduce and/or a gist or repository that demonstrates the defect.
- Then examples of the code you were using.
- Any error messages (including stacktrace, i.e. ""Show me the error.")
- Things you've tried.
- A pull request for your fix would be great. Code should have tests.
- Link to source code, if available.

Please make sure only to include one issue per report.
Copy link
Contributor

Choose a reason for hiding this comment

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

make sure to include only one

If you encounter multiple, unrelated issues, please report them as such.

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, although it is not specific to ActiveModelSerializers.
Copy link
Contributor

Choose a reason for hiding this comment

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

ActiveModel::Serializers I guess

Copy link
Member Author

Choose a reason for hiding this comment

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

But the library name is ActiveModelSerializers.. such confusion 🐶

Copy link
Contributor

Choose a reason for hiding this comment

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

maybe the official way to differentiate would be ActiveModelSerializers vs ActiveModel::Serializer -- one is an actual class?

Copy link
Contributor

Choose a reason for hiding this comment

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

The README talks of ActiveModel::Serializer. I don't have an opinion on which is better but we should remain consistent.

Copy link
Member Author

Choose a reason for hiding this comment

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

Yeah, in response to the above I changed it in the README. This gem suffers from naming confusion...

Copy link
Member

Choose a reason for hiding this comment

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

Yup, ActiveModelSerializers when not referring to the class.


The first place to start is by looking at our [GitHub Issues](https://github.com/rails-api/active_model_serializers/issues).
1. What have you tried?

The vast majority of development is happening under the `master` branch, currently slated for release as `0.10.x`. This is where we would suggest you start.
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.)

Fixing bugs is extraordinarily helpful and requires the least familiarity with AMS. 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).
This is extremely important for narrowing down the cause of your problem.

We are also 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). Some bugs are expressly not good for new contributors, so don't expect 100% overlap between the two.
Thanks!

If you want to work on new feature development, look for the label [**Feature**](https://github.com/rails-api/active_model_serializers/labels/Feature).
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 close is just an opportunity to help out some more, and then re-open.
Copy link
Contributor

Choose a reason for hiding this comment

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

"its being close" or "it getting closed"?


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

Thanks to everyone involved!

If you get help, sharing it back in the form of a pull-request or making an issue to document
Copy link
Member

Choose a reason for hiding this comment

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

Maybe mention the new docs?

Copy link
Member Author

Choose a reason for hiding this comment

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

agree, but not sure how to phrase it. can we defer?

Copy link
Member

Choose a reason for hiding this comment

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

"PRs, when including new behaviors should include whenever possible a new suitable recommendation about how to use the feature, you can find examples at /docs"

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).
Some bugs are expressly not good for new contributors, so don't expect 100% overlap between the two.
- [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.

- If you want to work on new feature development, look for the label [**Feature**](https://github.com/rails-api/active_model_serializers/labels/Feature).

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

Choose a reason for hiding this comment

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

RFC +1


## Issue Labeling

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

## Contributing

1. Fork it ( https://github.com/rails-api/active_model_serializers/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Write tests for your feature, or regression tests highlighting a bug
4. Write the feature itself, or fix your bug
5. Commit your changes (`git commit -am 'Add some feature'`)
6. Push to the branch (`git push origin my-new-feature`)
7. Create a new Pull Request
8. 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 under the proper version section.
9. Iterate on feedback given by the community (fix syntax, modify bits of code, add
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).

## 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
- Include links to any relevant github issues.
- *Don't* change the VERSION file.
- 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.

1. *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 under the proper version section.
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 and rebase off `master`.
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/)

### Running tests

Expand Down
4 changes: 2 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# ActiveModel::Serializer
# ActiveModelSerializers

[![Build Status](https://travis-ci.org/rails-api/active_model_serializers.svg?branch=master)](https://travis-ci.org/rails-api/active_model_serializers)
<a href="https://codeclimate.com/github/rails-api/active_model_serializers"><img src="https://codeclimate.com/github/rails-api/active_model_serializers/badges/gpa.svg" /></a>
<a href="https://codeclimate.com/github/rails-api/active_model_serializers/coverage"><img src="https://codeclimate.com/github/rails-api/active_model_serializers/badges/coverage.svg" /></a>

_Windows Build Status -_ [![Build status](https://ci.appveyor.com/api/projects/status/x6xdjydutm54gvyt/branch/master?svg=true)](https://ci.appveyor.com/project/joaomdmoura/active-model-serializers/branch/master)

ActiveModel::Serializer brings convention over configuration to your JSON generation.
ActiveModelSerializers brings convention over configuration to your JSON generation.

AMS does this through two components: **serializers** and **adapters**.
Serializers describe _which_ attributes and relationships should be serialized.
Expand Down
Binary file added docs/how-open-source-maintained.jpg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.