Merge pull request #520 from apiaryio/honzajavorek/warn-about-stable-tag

Introducing the stable tag

CONTRIBUTING.md

@@ -49,6 +49,20 @@ Also mind that CoffeeScript is production dependency (not dev dependency),
 because it's needed not only for compiling Dredd package before uploading
 to npm, but also for running user-provided hooks written in CoffeeScript.
 
+### Versioning
+
+Dredd follows [Semantic Versioning][]. To ensure certain stability of Dredd installations (e.g. in CI builds), users can pin their version. They can also use release tags:
+
+- `npm install dredd` - Installs the latest published version including experimental pre-release versions.
+- `npm install dredd@stable` - Skips experimental pre-release versions. Recommended for CI installations.
+
+When releasing, make sure you respect the tagging:
+
+- To release pre-release, e.g. `42.1.0-pre.7`, use just `npm publish`.
+- To release any other version, e.g. `42.1.0`, use `npm publish && npm dist-tag add [email protected] stable`.
+
+Hopefully this will be automated one day.
+
 ### Testing
 
 Use `npm run test` or just `npm test` to run all tests. Use `npm run test:bdd`
@@ -127,6 +141,7 @@ There are also some environment variables you could find useful:
 [Apiary]: https://apiary.io/
 [API Blueprint]: http://apiblueprint.org/
 
+[Semantic Versioning]: http://semver.org/
 [coffee-coverage]: https://github.com/benbria/coffee-coverage
 [coffeelint]: http://www.coffeelint.org/
 [CoffeeScript]: http://coffeescript.org

docs/overview.md

@@ -2,6 +2,13 @@
 
 Dredd works by taking your API description document, creating expectations based on the requests and responses in the description, making requests to your API, and seeing if the responses match. Dredd automatically builds these expectations from the API description every time the tests are run.
 
+## Versioning
+
+Dredd follows [Semantic Versioning][]. To ensure certain stability of your Dredd installation (e.g. in CI), pin the version accordingly. You can also use release tags:
+
+- `npm install dredd` - Installs the latest published version including experimental pre-release versions.
+- `npm install dredd@stable` - Skips experimental pre-release versions. Recommended for CI installations.
+
 ## Automatic Expectations
 
 Dredd automatically generates expectations on HTTP responses based on examples in the API description with use of [Gavel.js](https://github.com/apiaryio/gavel.js) library. Please refer to [Gavel](https://www.relishapp.com/apiary/gavel/docs) rules if you want know more.
@@ -367,6 +374,7 @@ info: Resource > Update resource > Example 1
 info: Resource > Update resource > Example 2
 ```
 
+[Semantic Versioning]: http://semver.org/
 [API Blueprint]: http://apiblueprint.org/
 [Travis CI]: https://travis-ci.org/
 [Gavel.js]: https://github.com/apiaryio/gavel.js

package.json

@@ -7,6 +7,8 @@
     "dredd": "bin/dredd"
   },
   "scripts": {
+    "postinstall": "coffee ./scripts/print-installation-guidelines.coffee",
+    "postupdate": "coffee ./scripts/print-installation-guidelines.coffee",
     "changelist": "github-changes -o apiaryio -r dredd --only-pulls --use-commit-body --file CHANGELOG-Generated.md -a",
     "lint": "coffeelint ./src",
     "docs:build": "mkdocs build",
@@ -31,6 +33,7 @@
     "chai": "^3.4.1",
     "clone": "^1.0.0",
     "coffee-script": "^1.10.0",
+    "colors": "^1.1.2",
     "dredd-transactions": "^1.2.0",
     "file": "~0.2.2",
     "gavel": "0.5.2",

scripts/print-installation-guidelines.coffee

@@ -0,0 +1,12 @@
+
+colors = require('colors')
+
+command = colors.bold(colors.yellow('npm install dredd@stable'))
+console.error(colors.cyan("""
+  ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+  ::                                                                ::
+  ::    Install Dredd using #{command} in case you    ::
+  ::        prefer stability over new features (e.g. in CI)         ::
+  ::                                                                ::
+  ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+"""))

src/transaction-runner.coffee

@@ -81,7 +81,6 @@ class TransactionRunner
             # - runs beforeValidation hooks
             # - runs Gavel validation
             @executeTransaction transaction, hooks, () =>
-
               return iterationCallback(@hookHandlerError) if @hookHandlerError?
 
               # run afterEach hooks