diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d55cbb8ed2..6bdbc4af05 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 . 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/ diff --git a/README.md b/README.md index ce746188ef..9917d591bb 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 0000000000..44fcc63439 --- /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 02b951c4be..511fb10597 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 @@
  • Home
  • GitHub
  • Feedback
    • +
  • Contributing Guide

    • Documentation