Rewrite the contributing guide

The goal behind this document should be to explain to new and potential
contributors what they need to do (and follow) to get involved and it
wasn't really doing that.

It should also be a document that we can link to when closing or explaining
reasoning behind decisions. Broadly, it should aim to ensure decisions
aren't just arbitary.

* Link to the contributing guide in the docs,
* Move repository/architecture discussion to the Contributing Guide,
* Document the use of labels (this matches those setup in GitHub),
* Document how releases happen and how it fits the hosted applications.

CONTRIBUTING.md

@@ -1,70 +1,130 @@
-# 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
 
 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 and/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/

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).

docs/contributing.md

@@ -0,0 +1 @@
+../CONTRIBUTING.md

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>