Rewrite the contributing guide

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>