kotovalexarian-likes-github/rails--rails
1
0
Fork 0
mirror of https://github.com/rails/rails.git synced 2022-11-09 12:12:34 -05:00
Code Releases Activity

Improve Contributing to Rails Guide

Browse source 
Logically group the content, so it makes more sense if someone tries to read from start of page to end of page. [ci skip]
This commit is contained in:
Gaurish Sharma 2014-04-06 02:26:43 +05:30
parent 3ae33961e0
commit 38ad5438cc
1 changed files with 122 additions and 104 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

226
guides/source/contributing_to_ruby_on_rails.md
View file

@ -69,89 +69,6 @@ won't be accepted." But it's the proper place to discuss new ideas. GitHub
Issues are not a particularly good venue for the sometimes long and involved
discussions new features require.
Setting Up a Development Environment
------------------------------------
To move on from submitting bugs to helping resolve existing issues or contributing your own code to Ruby on Rails, you _must_ be able to run its test suite. In this section of the guide you'll learn how to set up the tests on your own computer.
### The Easy Way
The easiest and recommended way to get a development environment ready to hack is to use the [Rails development box](https://github.com/rails/rails-dev-box).
### The Hard Way
In case you can't use the Rails development box, see section above, check [this other guide](development_dependencies_install.html).
Running an Application Against Your Local Branch
------------------------------------------------
The `--dev` flag of `rails new` generates an application that uses your local
branch:
```bash
$ cd rails
$ bundle exec rails new ~/my-test-app --dev
```
The application generated in `~/my-test-app` runs against your local branch
and in particular sees any modifications upon server reboot.
Testing Active Record
---------------------
This is how you run the Active Record test suite only for SQLite3:
```bash
$ cd activerecord
$ bundle exec rake test_sqlite3
```
You can now run the tests as you did for `sqlite3`. The tasks are respectively
```bash
test_mysql
test_mysql2
test_postgresql
```
Finally,
```bash
$ bundle exec rake test
```
will now run the four of them in turn.
You can also run any single test separately:
```bash
$ ARCONN=sqlite3 ruby -Itest test/cases/associations/has_many_associations_test.rb
```
You can invoke `test_jdbcmysql`, `test_jdbcsqlite3` or `test_jdbcpostgresql` also. See the file `activerecord/RUNNING_UNIT_TESTS.rdoc` for information on running more targeted database tests, or the file `ci/travis.rb` for the test suite run by the continuous integration server.
### Warnings
The test suite runs with warnings enabled. Ideally, Ruby on Rails should issue no warnings, but there may be a few, as well as some from third-party libraries. Please ignore (or fix!) them, if any, and submit patches that do not issue new warnings.
If you are sure about what you are doing and would like to have a more clear output, there's a way to override the flag:
```bash
$ RUBYOPT=-W0 bundle exec rake test
```
### Older Versions of Ruby on Rails
If you want to add a fix to older versions of Ruby on Rails, you'll need to set up and switch to your own local tracking branch. Here is an example to switch to the 3-0-stable branch:
```bash
$ git branch --track 3-0-stable origin/3-0-stable
$ git checkout 3-0-stable
```
TIP: You may want to [put your Git branch name in your shell prompt](http://qugstart.com/blog/git-and-svn/add-colored-git-branch-name-to-your-shell-prompt/) to make it easier to remember which version of the code you're working with.
Helping to Resolve Existing Issues
----------------------------------
@ -227,9 +144,21 @@ WARNING: Docrails has a very strict policy: no code can be touched whatsoever, n
Contributing to the Rails Code
------------------------------
### Clone the Rails Repository
### Setting Up a Development Environment ###
The first thing you need to do to be able to contribute code is to clone the repository:
To move on from submitting bugs to helping resolve existing issues or contributing your own code to Ruby on Rails, you _must_ be able to run its test suite. In this section of the guide you'll learn how to setup the tests on your own computer.
#### The Easy Way
The easiest and recommended way to get a development environment ready to hack is to use the [Rails development box](https://github.com/rails/rails-dev-box).
#### The Hard Way
In case you can't use the Rails development box, see section above, check [this other guide](development_dependencies_install.html).
### Clone the Rails Repository ###
To do to be able to contribute code, you need to clone the rails repository:
```bash
$ git clone git://github.com/rails/rails.git
@ -244,29 +173,32 @@ $ git checkout -b my_new_branch
It doesn't matter much what name you use, because this branch will only exist on your local computer and your personal repository on GitHub. It won't be part of the Rails Git repository.
### Write Your Code
### Running an Application Against Your Local Branch ###
Now get busy and add or edit code. You're on your branch now, so you can write whatever you want (you can check to make sure you're on the right branch with `git branch -a`). But if you're planning to submit your change back for inclusion in Rails, keep a few things in mind:
Incase, you need a dummy rails app to test change, The `--dev` flag of `rails new` generates an application that uses your local
branch:
```bash
$ cd rails
$ bundle exec rails new ~/my-test-app --dev
```
The application generated in `~/my-test-app` runs against your local branch
and in particular sees any modifications upon server reboot.
### Write Your Code ###
Now get busy and add/edit code. You're on your branch now, so you can write whatever you want (you can check to make sure you're on the right branch with `git branch -a`). But if you're planning to submit your change back for inclusion in Rails, keep a few things in mind:
* Get the code right.
* Use Rails idioms and helpers.
* Include tests that fail without your code, and pass with it.
* Update the (surrounding) documentation, examples elsewhere, and the guides: whatever is affected by your contribution.
It is not customary in Rails to run the full test suite before pushing
changes. The railties test suite in particular takes a long time, and even
more if the source code is mounted in `/vagrant` as happens in the recommended
workflow with the [rails-dev-box](https://github.com/rails/rails-dev-box).
As a compromise, test what your code obviously affects, and if the change is
not in railties, run the whole test suite of the affected component. If all
tests are passing, that's enough to propose your contribution. We have
[Travis CI](https://travis-ci.org/rails/rails) as a safety net for catching
unexpected breakages elsewhere.
TIP: Changes that are cosmetic in nature and do not add anything substantial to the stability, functionality, or testability of Rails will generally not be accepted.
### Follow the Coding Conventions
#### Follow the Coding Conventions
Rails follows a simple set of coding style conventions:
@ -284,7 +216,81 @@ Rails follows a simple set of coding style conventions:
The above are guidelines - please use your best judgment in using them.
### Updating the CHANGELOG
### Running Tests ###
It is not customary in Rails to run the full test suite before pushing
changes. The railties test suite in particular takes a long time, and even
more if the source code is mounted in `/vagrant` as happens in the recommended
workflow with the [rails-dev-box](https://github.com/rails/rails-dev-box).
As a compromise, test what your code obviously affects, and if the change is
not in railties, run the whole test suite of the affected component. If all
tests are passing, that's enough to propose your contribution. We have
[Travis CI](https://travis-ci.org/rails/rails) as a safety net for catching
unexpected breakages elsewhere.
#### Entire rails:
To run all the tests, do:
```bash
$ cd rails
$ bundle exec rake test
```
#### Particular component of rails
To run tests only for particular component(ActionPack, ActiveRecord etc). For example, to run `ActionMailer` test do
```bash
$ cd actionmailer
$ bundle exec rake test
```
##### Testing Active Record
This is how you run the Active Record test suite only for SQLite3:
```bash
$ cd activerecord
$ bundle exec rake test_sqlite3
```
You can now run the tests as you did for `sqlite3`. The tasks are respectively
```bash
test_mysql
test_mysql2
test_postgresql
```
Finally,
```bash
$ bundle exec rake test
```
will now run the four of them in turn.
You can also run any single test separately:
```bash
$ ARCONN=sqlite3 ruby -Itest test/cases/associations/has_many_associations_test.rb
```
You can invoke `test_jdbcmysql`, `test_jdbcsqlite3` or `test_jdbcpostgresql` also. See the file `activerecord/RUNNING_UNIT_TESTS.rdoc` for information on running more targeted database tests, or the file `ci/travis.rb` for the test suite run by the continuous integration server.
#### Single Test seprately
to run just one test. for example, to run `LayoutMailerTest` you can do:
```bash
$ cd actionmailer
$ ruby -w -Ilib:test test/mail_layout_test.rb
```
### Warnings ###
The test suite runs with warnings enabled. Ideally, Ruby on Rails should issue no warnings, but there may be a few, as well as some from third-party libraries. Please ignore (or fix!) them, if any, and submit patches that do not issue new warnings.
If you are sure about what you are doing and would like to have a more clear output, there's a way to override the flag:
```bash
$ RUBYOPT=-W0 bundle exec rake test
```
### Updating the CHANGELOG ###
The CHANGELOG is an important part of every release. It keeps the list of changes for every Rails version.
@ -309,7 +315,7 @@ A CHANGELOG entry should summarize what was changed and should end with author's
Your name can be added directly after the last word if you don't provide any code examples or don't need multiple paragraphs. Otherwise, it's best to make as a new paragraph.
### Sanity Check
### Sanity Check ###
You should not be the only person who looks at the code before you submit it.
If you know someone else who uses Rails, try asking them if they'll check out
@ -319,7 +325,7 @@ private before you push a patch out publicly is the “smoke test” for a patch
if you can’t convince one other developer of the beauty of your code, you’re
unlikely to convince the core team either.
### Commit Your Changes
### Commit Your Changes ###
When you're happy with the code on your computer, you need to commit the changes to Git:
@ -359,7 +365,7 @@ You can also add bullet points:
TIP. Please squash your commits into a single commit when appropriate. This simplifies future cherry picks, and also keeps the git log clean.
### Update Your Branch
### Update Your Branch ###
It's pretty likely that other changes to master have happened while you were working. Go get them:
@ -377,7 +383,7 @@ $ git rebase master
No conflicts? Tests still pass? Change still seems reasonable to you? Then move on.
### Fork
### Fork ###
Navigate to the Rails [GitHub repository](https://github.com/rails/rails) and press "Fork" in the upper right hand corner.
@ -507,7 +513,19 @@ $ 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
### Older Versions of Ruby on Rails ###
If you want to add a fix to older versions of Ruby on Rails, you'll need to set up and switch to your own local tracking branch. Here is an example to switch to the 3-0-stable branch:
```bash
$ git branch --track 3-0-stable origin/3-0-stable
$ git checkout 3-0-stable
```
TIP: You may want to [put your Git branch name in your shell prompt](http://qugstart.com/blog/git-and-svn/add-colored-git-branch-name-to-your-shell-prompt/) to make it easier to remember which version of the code you're working with.
#### 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.