Skip to content
Browse files

Follow up to 38ad543 [ci skip]

This commit adds new lines between titles, paragraphs and code blocks
for an easier reading.

Moreover, in order to be consistent with the other guides, let's remove
the sharps on the right side of the different titles.

The "Running a Single Test" part was also explained after the "Testing
Active Record" one which shows how to run a single test under the scope
of a specific adapter.

Finally, let's explain the `-n` option to run a specific test method.
  • Loading branch information...
1 parent 5c87c95 commit 4142a3019c3bbf2468beb3be84b1f506437a25b6 @robin850 robin850 committed May 2, 2014
Showing with 36 additions and 27 deletions.
  1. +36 −27 guides/source/contributing_to_ruby_on_rails.md
View
63 guides/source/contributing_to_ruby_on_rails.md
@@ -144,7 +144,7 @@ WARNING: Docrails has a very strict policy: no code can be touched whatsoever, n
Contributing to the Rails Code
------------------------------
-### Setting Up a Development Environment ###
+### 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 setup the tests on your own computer.
@@ -156,7 +156,7 @@ The easiest and recommended way to get a development environment ready to hack i
In case you can't use the Rails development box, see [this other guide](development_dependencies_install.html).
-### Clone the Rails Repository ###
+### Clone the Rails Repository
To be able to contribute code, you need to clone the Rails repository:
@@ -173,7 +173,7 @@ $ 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.
-### Running an Application Against Your Local Branch ###
+### Running an Application Against Your Local Branch
In case you need a dummy Rails app to test changes, the `--dev` flag of `rails new` generates an application that uses your local branch:
@@ -185,9 +185,9 @@ $ 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 ###
+### 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:
+Now get busy and add/edit code. You're on your branch now, so you can write whatever you want (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.
@@ -215,7 +215,8 @@ Rails follows a simple set of coding style conventions:
The above are guidelines - please use your best judgment in using them.
-### Running Tests ###
+### 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
@@ -228,20 +229,36 @@ tests are passing, that's enough to propose your contribution. We have
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` tests you can:
+
+#### For a Particular Component
+
+You can run tests only for a particular component (e.g. Action Pack). For example,
+to run Action Mailer tests:
```bash
$ cd actionmailer
$ bundle exec rake test
```
+#### Running a Single Test
+
+You can run a single test through ruby. For instance:
+
+```bash
+$ cd actionmailer
+$ ruby -w -Itest test/mail_layout_test.rb -n test_explicit_class_layout
+```
+
+The `-n` option allows you to run a single method instead of the whole
+file.
+
##### Testing Active Record
This is how you run the Active Record test suite only for SQLite3:
@@ -275,15 +292,7 @@ $ ARCONN=sqlite3 ruby -Itest test/cases/associations/has_many_associations_test.
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 separately
-to run just one test. For example, to run `LayoutMailerTest` you can:
-
-```bash
-$ cd actionmailer
-$ ruby -w -Ilib:test test/mail_layout_test.rb
-```
-
-### Warnings ###
+### 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.
@@ -292,7 +301,8 @@ If you are sure about what you are doing and would like to have a more clear out
```bash
$ RUBYOPT=-W0 bundle exec rake test
```
-### Updating the CHANGELOG ###
+
+### Updating the CHANGELOG
The CHANGELOG is an important part of every release. It keeps the list of changes for every Rails version.
@@ -317,7 +327,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
@@ -327,7 +337,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:
@@ -367,7 +377,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:
@@ -385,7 +395,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.
@@ -515,14 +525,13 @@ $ 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.
-
-### Older Versions of Ruby on Rails ###
+### 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
+$ git branch --track 4-0-stable origin/4-0-stable
+$ git checkout 4-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.

0 comments on commit 4142a30

Please sign in to comment.
Something went wrong with that request. Please try again.