Merge pull request #2 from mxenabled/robert/improve_readme

Improve README

Author: rodohanna

README.md

@@ -6,13 +6,110 @@ Keep your dependencies fashionably up-to-date.
 
 Vogue is a gradle plugin that reads and processes reports generated by the [gradle-versions-plugin](https://github.com/ben-manes/gradle-versions-plugin). This is intended to be used as a "gatekeeper" to prevent dependencies from getting too far out of date while also providing utilities to easily upgrade outdated dependencies.
 
+## Installing
+
+Vogue is hosted via [JitPack](https://jitpack.io/p/mxenabled/vogue).
+
+#### Gradle
+
+_build.gradle_:
+```groovy
+plugins {
+  id: "com.github.mxenabled.vogue" version "x.x.x"
+}
+
+allprojects {
+    repositories {
+        ...
+        maven { url "https://jitpack.io" }
+    }
+}
+```
+
+_settings.gradle_:
+```groovy
+pluginManagement {
+  repositories {
+    ...
+    maven { url "https://jitpack.io" }
+  }
+}
+```
+
+## Configuration
+
+Example configuration with default values:
+
+_In the build.gradle_
+```groovy
+vogue {
+  excludePreReleaseVersions = true // Set to false to include #.#.#.pre versions in the report.
+  dependencyUpdatesOutputDir = "build/dependencyUpdates" // Where the report generated by the `gradle-versions-plugin` is located.
+}
+```
+
+## Usage
+
+Scan the project dependencies and produce a report of available upgrades.
+```shell
+$ ./gradlew vogueReport
+```
+
+## Configuring Rules
+
+Rules can be configured in a version-controlled `.vogue.yml` file located at the root of the project. If a rule is violated,
+the report will return a failing status code (which can be used in a CI/CD pipeline).
+
+##### Global Defaults
+
+Global default rules can be configured via the following syntax:
+
+```yaml
+defaultRules:
+  major:
+    maxDiff: 1 # Every dependency can be at most one major version out-of-date, otherwise an error will be produced.
+  minor:
+    requireLatest: true # Every dependency must be on the latest minor version.
+  patch:
+    requireLatest: true # Every dependency must be on the latest patch version.
+```
+
+If no package-specific rule has been configured for a given dependency, the default rules will be used.
+
+##### Package Rules
+
+This syntax defines a rule for any `com.github.mxenabled.*` dependency and requires that you are always on the most current version.
+
+```yaml
+packageRules:
+  -
+    package: "com.github.mxenabled.*"
+    rules:
+      major:
+        requireLatest: true
+      minor:
+        requireLatest: true
+      patch:
+        requireLatest: true
+```
+
+## Suppressing Violations
+
+Occasionally you might need to suppress a dependency violation so that your CI/CD pipeline will pass (if you have Vogue configured as a required step).
+
+Running `vogueSuppress` will walk you through your dependency violations and allow you to suppress errors for a given time range (3 months max).
+```shell
+$ ./gradlew vogueSuppress
+```
+
 ## Deploying Locally
 
-To create a local build of the accessor to use in connector services use
+To create a local build of vogue use
 
 ```shell
 $ ./gradlew clean publishToMavenLocal
 ```
+
 This will create a local build in your local maven repository that you can
 then reference in other services.