docs(support): adds more examples and explanations in README

Also adds CONTRIBUTING.md which explains how to contribute to the project

Author: stalniy

CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to CASL
+
+I would love for you to contribute to CASL and help make it even better than it is
+today! As a contributor, here are the guidelines I would like you to follow:
+
+ - [Question or Problem?](#question)
+ - [Issues and Bugs](#issue)
+ - [Feature Requests](#feature)
+ - [Submission Guidelines](#submit)
+ - [Coding Rules](#rules)
+ - [Commit Message Guidelines](#commit)
+
+## <a name="question"></a> Got a Question or Problem?
+
+Do not open issues for general support questions as I want to keep GitHub issues for bug reports and feature requests. You've got much better chances of getting your question answered on [gitter chat][gitter].
+
+## <a name="issue"></a> Found a Bug?
+If you find a bug in the source code, you can help by [submitting an issue](#submit-issue) or even better, you can [submit a Pull Request](#submit-pr) with a fix.
+
+## <a name="feature"></a> Missing a Feature?
+You can *request* a new feature by [submitting an issue](#submit-issue) to this GitHub Repository. If you would like to *implement* a new feature, please submit an issue with a proposal for your work first, to be sure that somebody else hasn't started to do the same.
+
+## <a name="submit"></a> Submission Guidelines
+
+### <a name="submit-issue"></a> Submitting an Issue
+
+Before you submit an issue, please search the issue tracker, maybe an issue for your problem already exists and the discussion might inform you of workarounds readily available.
+
+Please provide steps to reproduce for found bug (using http://plnkr.co or similar), this will help to understand and fix the issue faster.
+
+### <a name="submit-pr"></a> Submitting a Pull Request (PR)
+Before you submit your Pull Request (PR) consider the following guidelines:
+
+* Search [GitHub](https://github.com/stalniy/casl/pulls) for an open or closed PR
+  that relates to your submission. You don't want to duplicate effort.
+* Make your changes in a new git branch:
+
+     ```sh
+     git checkout -b my-fix-branch master
+     ```
+
+* **include appropriate test cases**.
+* Follow defined [Coding Rules](#rules).
+* Run all test suites `npm test`
+* Commit your changes using a descriptive commit message that follows defined [commit message conventions](#commit). Adherence to these conventions is necessary because release notes are automatically generated from these messages.
+* Push your branch to GitHub:
+
+    ```shell
+    git push origin my-fix-branch
+    ```
+* In GitHub, send a pull request to `casl:master`.
+* If somebody from project contributors suggest changes then:
+  * Make the required updates.
+  * Re-run all test suites to ensure tests are still passing.
+  * Rebase your branch and force push to your GitHub repository (this will update your Pull Request). Basically you can use `git commit -a --amend` and `git push --force origin my-fix-branch` in order to keep single commit in the feature branch.
+
+That's it! Thank you for your contribution!
+
+## <a name="rules"></a> Coding Rules
+To ensure consistency throughout the source code, keep these rules in mind as you are working:
+
+* All features or bug fixes **must be tested** by one or more specs (unit-tests).
+* All public API methods **must be documented**.
+* Project follows [Airbnb's JavaScript Style Guide][js-style-guide] with [some exceptions](.eslintrc). All these will be checked by Travis ci when you submit your PR
+
+## <a name="commit"></a> Commit Message Guidelines
+
+The project have very precise rules over how git commit messages can be formatted.  This leads to **more readable messages** that are easy to follow when looking through the **project history**.  But also, git history is used to **generate the change log**.
+
+The commit message format is borrowed from Angular projects and you can find [more details in this document][commit-message-format]
+
+[commit-message-format]: https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#
+[github]: https://github.com/stalniy/casl
+[gitter]: https://gitter.im/stalniy-casl/casl
+[js-style-guide]: https://github.com/airbnb/javascript

README.md

@@ -3,6 +3,8 @@
 [![NPM version](https://badge.fury.io/js/casl.svg)](http://badge.fury.io/js/casl)
 [![Build Status](https://travis-ci.org/stalniy/casl.svg?branch=master)](https://travis-ci.org/stalniy/casl)
 [![codecov](https://codecov.io/gh/stalniy/casl/branch/master/graph/badge.svg)](https://codecov.io/gh/stalniy/casl)
+[![Join the chat at https://gitter.im/stalniy-casl/casl](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/stalniy-casl/casl?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+
 
 CASL is an isomorphic authorization JavaScript library which restricts what resources a given user is allowed to access. All permissions are defined in a single location (the `Ability` class) and not duplicated across controllers, views, and database queries.
 
@@ -20,6 +22,128 @@ npm install casl --save
 * supports direct and inverted rules
 * provides [mongoose](https://github.com/Automattic/mongoose) plugin
 * can be easily integrated with any data storage
+* provides ES6 build, so you are able to shake out unused functionality
+
+## Getting started
+
+CASL allows you to use any data layer (e.g., `mongoose`, raw `mongodb` adapter, `sequalize`) and any HTTP framework (e.g., `koa`, `express`, `feathersjs`). It doesn't force you to choose even a database (however currently is the best integrated with MongoDB).
+
+CASL concentrates all attention at what a user can actually do and allows to create abilities in DSL style. Lets see how
+
+### 1. Define Abilities
+
+Lets define `Ability` for a blog website where visitors:
+* can read everything.
+* can manage (i.e., create, update, delete, read) posts which were created by them
+* cannot delete post if it has at least 1 comment
+
+```js
+import { AbilityBuilder } from 'casl'
+
+const ability = AbilityBuilder.define((can, cannot) => {
+  can('read', 'all')
+  can('manage', 'Post', { author: loggedInUser.id })
+  cannot('delete', 'Post', { 'comments.0': { $exists: true } })
+})
+```
+
+Yes, you can use some operators from MongoDB query language to define conditions for your abilities.
+
+### 2. Check Abilities
+
+Later on you can check abilities using `can` and `cannot`.
+```js
+// true if ability allows to read at least one Post
+ability.can('read', 'Post')
+
+// true if ability does not allow to read a post
+const post = new Post({ title: 'What is CASL?' })
+ability.cannot('read', post)
+```
+Also there is a conveninse method `throwUnlessCan` which throws `ForbiddenError` exception in case if action is not allowed on target object:
+```js
+import { ForbiddenError } from 'casl'
+
+try {
+  ability.throwUnlessCan('delete', post)
+} catch (error) {
+  console.log(error instanceof Error) // true
+  console.log(error instanceof ForbiddenError) // true
+}
+```
+
+### 3. MongoDB integration
+
+CASL provides easy integration with MongoDB database.
+```js
+const { toMongoQuery, AbilityBuilder } = require('casl')
+const { MongoClient } = require('mongodb')
+
+const ability = AbilityBuilder.define(can => {
+  can('read', 'Post', { author: 'me' })
+})
+
+MongoClient.connect('mongodb://localhost:27017/blog', function(err, db) {
+  const query = toMongoQuery(ability.rulesFor('read', 'Post')) // { $or: [{ author: 'me' }] }
+  db.collection('posts').find(query) // find all Posts where author equals 'me'
+  db.close();
+})
+```
+
+And if you use [mongoose](https://github.com/Automattic/mongoose), you are lucky because CASL provides mongoose middleware which hides all boilerplate under convenient `accessibleBy` method.
+```js
+const { mongoosePlugin, AbilityBuilder } = require('casl')
+const mongoose = require('mongoose')
+
+mongoose.plugin(mongoosePlugin)
+
+const ability = AbilityBuilder.define(can => {
+  can('read', 'Post', { author: 'me' })
+})
+
+const Post = mongoose.model('Post', mongoose.Schema({
+  title: String,
+  author: String,
+  content: String,
+  createdAt: Date
+}))
+
+// by default if asks for `read` rules
+// returns mongoose Query, so you can chain it with other conditions
+Post.accessibleBy(ability).where({ createdAt: { $gt: Date.now() - 24 * 3600 } })
+
+// also you can call it on existing query to enforce visibility.
+// In this case it returns empty array because rules does not allow to read Posts of `someoneelse` author
+Post.find({ author: 'someoneelse' }).accessibleBy(ability).exec()
+```
+
+### 4. UI integration
+
+CASL is written in pure ES6 and has no dependencies on Node.js or other environments. That means you can use it on UI side. It may be useful if you need to show/hide some UI functionality based on what user can do in application.
+
+```js
+import { Ability } from 'casl'
+
+export class Session {
+  constructor() {
+    this.ability = new Ability()
+  }
+
+  find() {
+    return fetch('https://domain.com/session')
+      .then(session => this.ability.update(session.rules))
+  }
+
+  destroy() {
+    return fetch('https://domain.com/session', { method: 'DELETE' })
+      .then(() => this.ability.update([]))
+  }
+}
+```
+
+## Want to help?
+
+Want to file a bug, contribute some code, or improve documentation? Excellent! Read up on guidelines for [contributing](CONTRIBUTING.md)
 
 ## License