Contributing Guide

Code of Conduct

We welcome pull requests from everyone. By participating in this project, you agree to abide by the thoughtbot code of conduct.

We expect everyone to follow the code of conduct anywhere in thoughtbot's project codebases, issue trackers, chat-rooms, and mailing lists.

Getting Started

Administrate is a Rails Engine, but ships with everything needed to contribute and test new changes.

To maintain compatibility with multiple dependency versions, we use Appraisal.

Opening a PR

  1. Fork the repo,
  2. Run ./bin/setup to install the base dependencies and setup a local database,
  3. Run the test suite: bundle exec rspec && bundle exec appraisal rspec,
  4. Make your changes,
  5. Push your fork and open a pull request.

A good PR will solve the smallest problem it possibly can, have good test coverage and (where necessary) have internationalisation support.

Running the application locally

Administrate's demo application can be run like any Rails application:

bundle exec rails s

This will start the application defined in spec/example_app. You can view the example_app in the browser by navigating to /admin

Repository Structure

Rails configuration files have been changed to recognize the app in the new location, so running the server or deploying to Heroku works normally.

With this structure, developing a typical feature looks like:

Front-end Architecture

This project uses:


Issues and PRs are split into two levels of labels, at the higher level:

…and then to more specific themes:


See the security policy.


New releases (and the time period between them) is arbitrary, but usually motivated by a new Rails release or enough bug fixes or features that there's significant enough changes.

A new release involves cutting and pushing a new version to Ruby Gems and then deploying that version of the example application and documentation. This means that the demo application always matches the current release, whilst the pre-release application will track current master.