diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d55cbb8ed25855865694ca8e5b9264b5f53cfc09..dcaaff685eb1796561ffe1e6d7ef79912204745d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,61 +1,110 @@
-# Contributing
+# Contributing Guide
-We love pull requests from everyone.
-By participating in this project,
-you agree to abide by the thoughtbot [code of conduct].
+## Code of Conduct
-We expect everyone to follow the code of conduct
-anywhere in thoughtbot's project codebases,
-issue trackers, chatrooms, and mailing lists.
+We welcome pull requests from everyone. By participating in this project, you
+agree to abide by the thoughtbot [code of conduct].
-1. Fork the repo.
+We expect everyone to follow the code of conduct anywhere in thoughtbot's
+project codebases, issue trackers, chat-rooms, and mailing lists.
-1. Run `./bin/setup`.
+[code of conduct]: https://thoughtbot.com/open-source-code-of-conduct
+
+## 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][].
+
+[Rails Engine]: https://guides.rubyonrails.org/engines.html
+[Appraisal]: https://github.com/thoughtbot/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
-1. Run `appraisal install`
+Administrate's demo application can be run like any Rails application:
-1. Run the tests. We only take pull requests with passing tests, and it's great
- to know that you have a clean slate: `bundle exec rake && bundle exec appraisal rake`
+```sh
+bundle exec rails s
+```
-1. Add a test for your change. Only refactoring and documentation changes
- require no new tests. If you are adding functionality or fixing a bug,
- we need a test!
+This will start the application defined in `spec/example_app`.
-1. Make the test pass.
+## Repository Structure
-1. Write a [good commit message][commit].
+* The gem's source code lives in the `app` and `lib` subdirectories.
+* The demo app is nested within `spec/example_app`.
+* The guides as seen at
+ [https://administrate-demo.herokuapp.com][docs] live as
+ Markdown files in the `docs` subdirectory.
-1. Push to your fork and submit a pull request.
+Rails configuration files have been changed
+to recognize the app in the new location,
+so running the server or deploying to Heroku works normally.
-Others will give constructive feedback.
-This is a time for discussion and improvements,
-and making the necessary changes will be required before we can
-merge the contribution.
+With this structure, developing a typical feature looks like:
-## Start Application in Development
+* Add tests in `spec/`
+* Implement a feature in `administrate/`
+* Exercise the feature using the demo rails app (`spec/example_app/app/`)
-Configure your local environment with `./bin/setup`.
-After that start the application with the `foreman start` command.
+[demo]: https://administrate-prototype.herokuapp.com/admin
+[docs]: https://administrate-prototype.herokuapp.com
-## Performance Improvements
+## Front-end Architecture
-Improving our users' experience should be the primary goal of any optimization.
+This project uses:
-If you contribute a performance improvement,
-you must submit performance profiles
-that show that your optimizations
-make a significant impact
-on Administrate's request times.
+* Sass
+* [BEM]-style CSS selectors, with [namespaces]
+* Autoprefixer
+* SCSS-Lint, with [Hound] ([configuration](.scss-lint.yml))
+* A variety of CSS units:
+ - `em` for typographical-related elements
+ - `rem` for lengths related to components
+ - `px` for borders, text shadows, etc.
+ - `vw`/`vh` for lengths that should be relational to the viewport
-Request-level profiles are our best measure
-of how users experience our app.
-Many other performance measurements,
-such as benchmarks,
-can give inaccurate impressions
-of an optimization's overall impact.
+[BEM]: http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/
+[namespaces]: http://csswizardry.com/2015/03/more-transparent-ui-code-with-namespaces/
+[Hound]: https://houndci.com/
-Tools like [Rack MiniProfiler] are helpful
-for generating request-level performance profiles.
+## Labels
+
+Issues and PRs are split into two levels of labels, at the higher level:
+
+* `feature`: new functionality that’s not yet implemented,
+* `bug`: breakages in functionality that is implemented,
+* `maintenance`: to keep up with changes around us
+
+…and then to more specific themes:
+
+* `namespacing`: models with a namespace,
+* `installing`: initial setup, first-run experience, generators,
+* `i18n`: translations and language support,
+* `views-and-styles`: how administrate looks and is interacted with,
+* `dashboards`: how administrate presents fields and displays data,
+* `search`: finding things through our models,
+* `sorting`: ordering things on dashboards,
+* `pagination`: how we handle lots of data in small chunks,
+* `security`: controlling data access through authorisation,
+* `fields`: new fields, displaying and editing data,
+* `models`: models, associations and fetching the underlying data,
+* `documentation`: how to use Administrate, examples and common usage,
+* `dependencies`: changes or issues relating to a dependency
## Security
@@ -63,8 +112,19 @@ For security inquiries or vulnerability reports, please email
<security@thoughtbot.com>.
If you'd like, you can use our [PGP key] when reporting vulnerabilities.
-[code of conduct]: https://thoughtbot.com/open-source-code-of-conduct
-[commit]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
-[Rack MiniProfiler]: https://github.com/MiniProfiler/rack-mini-profiler
[PGP key]: https://thoughtbot.com/thoughtbot.asc
+## Releasing
+
+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][demo] always matches the current release,
+whilst [the pre-release application][pre-release] can track current `master`.
+
+[Ruby Gems]: https://rubygems.org/gems/administrate
+[demo]: https://administrate-demo.herokuapp.com/
+[pre-release]: https://administrate-demo-prerelease.herokuapp.com/
diff --git a/README.md b/README.md
index ce746188ef03b302e116772f1a9bc6d7b1df5627..9917d591bbcbf170cdc79498642099e7ec865735 100644
--- a/README.md
+++ b/README.md
@@ -97,46 +97,6 @@ see the guides at
These guides are available as markdown files in the `docs` subdirectory of the
git repository, too.
-## Repository Structure
-
-This repository contains both the source code for Administrate,
-and a demo Rails app that uses Administrate.
-The demo app is [hosted publicly on Heroku][demo].
-
-- The gem's source code lives in the `app` and `lib` subdirectories.
-- The demo app is nested within `spec/example_app`.
-- The guides as seen at
- [https://administrate-prototype.herokuapp.com][prototype_heroku] live as
- markdown files in the `docs` subdirectory.
-
-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:
-
-- Add tests in `spec/`
-- Implement a feature in `administrate/`
-- Exercise the feature using the demo rails app (`spec/example_app/app/`)
-
-## Front-end Architecture
-
-This project uses:
-
-- Sass
-- [BEM]-style CSS selectors, with [namespaces]
-- Autoprefixer
-- SCSS-Lint, with [Hound] ([configuration](.scss-lint.yml))
-- A variety of CSS units:
- - `em` for typographical-related elements
- - `rem` for lengths related to components
- - `px` for borders, text shadows, etc.
- - `vw`/`vh` for lengths that should be relational to the viewport
-
-[BEM]: http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/
-[namespaces]: http://csswizardry.com/2015/03/more-transparent-ui-code-with-namespaces/
-[Hound]: https://houndci.com/
-
## Contributing
Please see [CONTRIBUTING.md](/CONTRIBUTING.md).
diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 120000
index 0000000000000000000000000000000000000000..44fcc63439371c8c829df00eec6aedbdc4d0e4cd
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1 @@
+../CONTRIBUTING.md
\ No newline at end of file
diff --git a/spec/example_app/app/views/layouts/docs.html.erb b/spec/example_app/app/views/layouts/docs.html.erb
index 02b951c4be7f9883b5c88e893527d4031f47dcd3..511fb10597fb0d0ada54042bbf0b06c2c86f64bd 100644
--- a/spec/example_app/app/views/layouts/docs.html.erb
+++ b/spec/example_app/app/views/layouts/docs.html.erb
@@ -14,6 +14,7 @@
<li><a href="/">Home</a></li>
<li><a href="https://github.com/thoughtbot/administrate">GitHub</a></li>
<li><a href="https://github.com/thoughtbot/administrate/issues/new">Feedback</a></li>
+ <li><a href="/contributing">Contributing Guide</a></li>
</ul>
<h3>Documentation</h3>