Merge pull request #96 from dkniffin/update-readme-and-contributing

Update README and CONTRIBUTING.md

CONTRIBUTING.md

@@ -1,11 +1,45 @@
-## Contributing
+# Contributing
+
+Thank you for considering a contribution to this project!
+
+## Create an issue
+
+If you find an issue, or you'd like to request a new feature, [open a github issue](https://github.com/dkniffin/active_material/issues/new).
+
+## Submit a pull request
+
+If you know how to make the change, please submit a pull request (PR). This makes it much easier to
+accept the change
 
 1. Fork it ( https://github.com/[my-github-username]/active_material/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am "Add some feature"`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
 
-### Issue and PR reviews
+In order for the PR to be merged, the test suite must pass, there must be no conflicts on the
+merge, and it must be merged by a maintainer.
+
+## Issue and PR reviews
 
 Another way you can help is by reviewing issues, trying to reproduce bugs, and providing feedback on PRs.
+
+## Pushing a new version
+
+First, you must be authorized on both rubygems.org and npmjs.com. Then:
+
+1. Update the ruby gem:
+  - Update the version in `lib/active_material/version.rb`
+  - `gem build active_material.gemspec`
+  - `gem push active_material-X.Y.Z.gem`
+
+2. Update the npm package:
+  - Update the version in `package.json`
+  - `npm publish`
+
+3. Update the changelog.
+
+4. Tag the version in git:
+  - `git tag X.Y.Z`
+  - Add the same text as the changelog to the tag description
+  - `git push origin X.Y.Z`

README.md

@@ -5,17 +5,34 @@ An ActiveAdmin skin based on Google's Material Design.
 <img src="http://i.imgur.com/kDkGzYe.png">
 
 ## Installation
+### Importmap
 
+- Add `gem 'active_material'` to `Gemfile` and run `bundle install`
+- Add `import "active_material"` to JS entrypoint (a JS file that is included for activeadmin)
+- Add `@import "active_material";` in your CSS style file (the active_material SCSS files are included in the asset path automatically, but you will need to have SCSS build capabilities, using dartsass-rails or similar)
+
+NOTE: no need to pin the import in your application. That's handled internally by the gem.
+
+### npm
 - `npm install --save active_material` or `yarn add active_material`
-- Add `@import "active_material/src/stylesheets/active_material.scss";` to your CSS style file (eg `app/javascript/packs/active_admin.scss`). *Note:* this requires that your build system supports compiling SCSS
-- Add `import "active_material"` to your JS file (eg `app/javascript/packs/active_admin.js`)
+- Add `import "active_material"` to your JS pack file
+- Add `@import "active_material/app/assets/stylesheets/active_material.scss";` to your CSS style file
+
+## Options
+
+### Change font
+
+By default, this gem will load the Roboto font from google APIs and use it in the SCSS. If you would like to change that behavior, you have a few options:
+
+1. If you want to change to another font:
+    - In your application config, set `config.active_material.font_url` to your font url
+    - In your SCSS file, just before `@import "active_material";`, add `$am-font-sans: 'Roboto';`, replacing `Roboto` with your font name.
+2. If you want to disable font loading altogether, you can use `config.active_material.load_font = true`
+
+### Other customizations
 
-## Upgrading from v1 to v2
+For other customization options, see [customization.md](./docs/customization.md)
 
-This activeadmin theme is entirely JS and CSS, and there is no custom ruby code. Therefore, since v2, active_material has been converted from a ruby gem to an npm/JS package. As part of this process, sprockets is also no longer supported.
+## Contributing
 
-To upgrade from v1 to v2, follow these steps:
-1. Follow the instructions above for "installation" to add the npm version
-2. Remove references to active_material in `app/assets/stylesheets/active_admin.scss`. Any customizations should be moved over to wherever the new scss import is.
-3. Remove references to active_material in `app/assets/javascripts/active_admin.js`.
-4. Remove the `gem 'active_material'` from your Gemfile (and run `bundle install` to update Gemfile.lock)
+See [CONTRIBUTING.md](./CONTRIBUTING.md)