Fetching contributors…
Cannot retrieve contributors at this time
145 lines (99 sloc) 4.02 KB


First off, thank you for considering contributing to Active Admin. It's people like you that make Active Admin such a great tool.

1. Where do I go from here?

If you've noticed a bug or have a question that doesn't belong on the mailing list or Stack Overflow, search the issue tracker to see if someone else in the community has already created a ticket. If not, go ahead and make one!

2. Fork & create a branch

If this is something you think you can fix, then fork Active Admin and create a branch with a descriptive name.

A good branch name would be (where issue #325 is the ticket you're working on):

git checkout -b 325-add-japanese-translations

3. Get the test suite running

Install the development dependencies:

bundle install

Now you should be able to run the entire suite using:

rake test

Which will generate a rails application in spec/rails to run the tests against.

If your tests are passing locally but they're failing on Travis, reset your test environment:

rm -rf spec/rails && bundle update

4. Implement your fix or feature

At this point, you're ready to make your changes! Feel free to ask for help; everyone is a beginner at first 😸

5. View your changes in a Rails application

Active Admin is meant to be used by humans, not cucumbers. So make sure to take a look at your changes in a browser.

To boot up a test Rails app:

script/local server

This will automatically create a Rails app if none already exists, and store it in the .test-rails-apps folder. The currently active app is symlinked to test-rails-app.

If you have any Bundler issues, call the use_rails script then prepend the version of rails you would like to use in an environment variable:

script/use_rails 4.0.0
RAILS=4.0.0 script/local server

You should now be able to open http://localhost:3000/admin in your browser. You can log in using:

Password: password

If you need to perform any other commands on the test application, use the local script. For example:

To boot the rails console:

script/local console

Or to migrate the database:

script/local rake db:migrate

6. Run tests against major supported rails versions

Once you've implemented your code, got the tests passing, previewed it in a browser, you're ready to test it against multiple versions of Rails.

rake test:major_supported_rails

This runs our test suite against a couple of major versions of Rails. Travis does essentially the same thing when you open a Pull Request. We care about quality, so your PR won't be merged until all tests pass.

7. Make a Pull Request

At this point, you should switch back to your master branch and make sure it's up to date with Active Admin's master branch:

git remote add upstream
git checkout master
git pull upstream master

Then update your feature branch from your local copy of master, and push it!

git checkout 325-add-japanese-translations
git rebase master
git push --set-upstream origin 325-add-japanese-translations

Finally, go to GitHub and make a Pull Request :D

8. Keeping your Pull Request updated

If a maintainer asks you to "rebase" your PR, they're saying that a lot of code has changed, and that you need to update your branch so it's easier to merge.

To learn more about rebasing in Git, there are a lot of good resources, but here's the suggested workflow:

git checkout 325-add-japanese-translations
git pull --rebase upstream master
git push -f 325-add-japanese-translations