diff options
Diffstat (limited to 'guides/source/contributing_to_ruby_on_rails.md')
| -rw-r--r-- | guides/source/contributing_to_ruby_on_rails.md | 46 |
1 files changed, 42 insertions, 4 deletions
diff --git a/guides/source/contributing_to_ruby_on_rails.md b/guides/source/contributing_to_ruby_on_rails.md index 3791467584..feb32eb06f 100644 --- a/guides/source/contributing_to_ruby_on_rails.md +++ b/guides/source/contributing_to_ruby_on_rails.md @@ -9,7 +9,7 @@ This guide covers ways in which _you_ can become a part of the ongoing developme * Contributing to the Ruby on Rails documentation * Contributing to the Ruby on Rails code -Ruby on Rails is not "someone else's framework." Over the years, hundreds of people have contributed to Ruby on Rails ranging from a single character to massive architectural changes or significant documentation -- all with the goal of making Ruby on Rails better for everyone. Even if you don't feel up to writing code or documentation yet, there are a variety of other ways that you can contribute, from reporting issues to testing patches. +Ruby on Rails is not "someone else's framework." Over the years, hundreds of people have contributed to Ruby on Rails ranging from a single character to massive architectural changes or significant documentation — all with the goal of making Ruby on Rails better for everyone. Even if you don't feel up to writing code or documentation yet, there are a variety of other ways that you can contribute, from reporting issues to testing patches. -------------------------------------------------------------------------------- @@ -24,7 +24,7 @@ NOTE: Bugs in the most recent released version of Ruby on Rails are likely to ge If you've found a problem in Ruby on Rails which is not a security risk, do a search in GitHub under [Issues](https://github.com/rails/rails/issues) in case it was already reported. If you find no issue addressing it you can [add a new one](https://github.com/rails/rails/issues/new). (See the next section for reporting security issues). -At the minimum, your issue report needs a title and descriptive text. But that's only a minimum. You should include as much relevant information as possible. You need at least to post the code sample that has the issue. Even better is to include a unit test that shows how the expected behavior is not occurring. Your goal should be to make it easy for yourself -- and others -- to replicate the bug and figure out a fix. +At the minimum, your issue report needs a title and descriptive text. But that's only a minimum. You should include as much relevant information as possible. You need at least to post the code sample that has the issue. Even better is to include a unit test that shows how the expected behavior is not occurring. Your goal should be to make it easy for yourself — and others — to replicate the bug and figure out a fix. Then, don't get your hopes up! Unless you have a "Code Red, Mission Critical, the World is Coming to an End" kind of bug, you're creating this issue report in the hope that others with the same problem will be able to collaborate with you on solving it. Do not expect that the issue report will automatically see any activity or that others will jump to fix it. Creating an issue like this is mostly to help yourself start on the path of fixing the problem and for others to confirm it with an "I'm having this problem too" comment. @@ -146,7 +146,7 @@ After applying their branch, test it out! Here are some things to think about: Once you're happy that the pull request contains a good change, comment on the GitHub issue indicating your approval. Your comment should indicate that you like the change and what you like about it. Something like: <blockquote> -I like the way you've restructured that code in generate_finder_sql -- much nicer. The tests look good too. +I like the way you've restructured that code in generate_finder_sql — much nicer. The tests look good too. </blockquote> If your comment simply says "+1", then odds are that other reviewers aren't going to take it too seriously. Show that you took the time to review the pull request. @@ -215,7 +215,7 @@ Rails follows a simple set of coding style conventions. * Use a = b and not a=b. * Follow the conventions in the source you see used already. -The above are guidelines -- please use your best judgment in using them. +The above are guidelines — please use your best judgment in using them. ### Updating the CHANGELOG @@ -376,6 +376,44 @@ Now you need to get other people to look at your patch, just as you've looked at It’s entirely possible that the feedback you get will suggest changes. Don’t get discouraged: the whole point of contributing to an active open source project is to tap into community knowledge. If people are encouraging you to tweak your code, then it’s worth making the tweaks and resubmitting. If the feedback is that your code doesn’t belong in the core, you might still think about releasing it as a gem. +#### Squashing commits + +One of the things that we may ask you to do is "squash your commits," which +will combine all of your commits into a single commit. We prefer pull requests +that are a single commit. This makes it easier to backport changes to stable +branches, squashing makes it easier to revert bad commits, and the git history +can be a bit easier to follow. Rails is a large project, and a bunch of +extraneous commits can add a lot of noise. + +In order to do this, you'll need to have a git remote that points at the main +Rails repository. This is useful anyway, but just in case you don't have it set +up, make sure that you do this first: + +```bash +$ git remote add upstream https://github.com/rails/rails.git +``` + +You can call this remote whatever you'd like, but if you don't use `upstream`, +then change the name to your own in the instructions below. + +Given that your remote branch is called `my_pull_request`, then you can do the +following: + +```bash +$ git fetch upstream +$ git checkout my_pull_request +$ git rebase upstream/master +$ git rebase -i + +< Choose 'squash' for all of your commits except the first one. > +< Edit the commit message to make sense, and describe all your changes. > + +$ git push origin my_pull_request -f +``` + +You should be able to refresh the pull request on GitHub and see that it has +been updated. + ### Backporting Changes that are merged into master are intended for the next major release of Rails. Sometimes, it might be beneficial for your changes to propagate back to the maintenance releases for older stable branches. Generally, security fixes and bug fixes are good candidates for a backport, while new features and patches that introduce a change in behavior will not be accepted. When in doubt, it is best to consult a Rails team member before backporting your changes to avoid wasted effort. |