Promote to 1.0.0 and more details in the documentation (#4)

* Promote to 1.0.0 and more details in the documentation

CHANGELOG.md

@@ -7,11 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0] - 2019-01-07
+
+No changes; decided to promote to 1.0.0 thanks to its stability. More details in the documentation.
+
 ## [0.3.0] - 2018-12-13
 
 ### Added
 
-- The pool boy can check if a floating body is dead or alive before cleaning it from the pool.
+- The pool boy can check, by querying the Concourse ATC, if a floating body is dead or alive before cleaning it from the pool.
 
 ## [0.2.0] - 2018-12-03
 

README.md

@@ -1,19 +1,18 @@
 # Concourse pool boy
 
-Like a an efficient pool boy, keep the pools of the [Concourse pool-resource] clean from debris.
-
-For an even smarter pool boy, you can tell him to check if a floating body is still alive before
-cleaning it by using our improved [Pix4D pool-resource] and setting the parameters
-`CONCOURSE_BASE_URL`, `CONCOURSE_USERNAME` and `CONCOURSE_PASSWORD` (see below).
+Observes the pools used by the *Concourse pool resource* and resets to unclaimed any lock that it determines **stale**.
 
 Can be used from the command-line or from a Concourse pipeline.
 
+We strongly suggest to use our [forked version of the Concourse pool-resource], since this enables the Pool Boy to query the ATC and determine if a lock is stale based on correct liveliness information about the job which acquired it. To enable the Pool Boy to query the ATC, see section "Enabling ATC querying".
+
+On the other hand, if paired with the original Concourse pool resource, the only criterion it can use for staleness is a timeout, so it is possible for the Pool Boy to steal a lock out of a perfectly fine job and cause mayhem when the job that owned the lock attempts to unclaim it.
+
 ## Status
 
-This software is currently beta, although we are already using it in production.
+We have been using this software in production, periodically triggered by a Concourse pipeline, for a few months and it is stable to use.
 
-Following semver numbering, expect API breakages until it reaches major version 1.
-We suggest to pin to a specific commit and perform tests before upgrading.
+We follow semver numbering. We suggest to pin to a specific commit and perform tests before upgrading.
 
 See also the [CHANGELOG](CHANGELOG.md).
 
@@ -78,17 +77,23 @@ jobs:
           POOLS: POOL_1:STALE_TIMEOUT_1,POOL_2:STALE_TIMEOUT_2
 ```
 
+## Enabling ATC querying
+
+To enable the Pool Boy to query the ATC and determine if a lock is stale based on correct liveliness information about the job which acquired it:
+
+1. Use our [forked version of the Concourse pool-resource].
+2. Set `CONCOURSE_BASE_URL`, `CONCOURSE_USERNAME` and `CONCOURSE_PASSWORD` as follows.
+
 `CONCOURSE_BASE_URL` is optional. It should be identical to the `--concourse-url` value passed to
 `fly`. If present the `CONCOURSE_USERNAME` and `CONCOURSE_PASSWORD` are mandatory and they must be
 valid Concourse credential with the appropriate rights to see the status of the builds that uses
 the configured `POOL_REPO`.
 
 ## Caveats
 
-Note that if the `CONCOURSE_BASE_URL` is not specified, the pool boy won't be able to validate if
-the build that last claimed a lock is still alive or not and will then rely solely on the staleness
-timeout configured. This will typically result in a pipeline failure when the following sequence of
-events happen:
+Note that if you don't follow section "Enabling ATC querying", then the Pool Boy won't be able to validate if the build that last claimed a lock is still alive or not and will then rely solely on the staleness timeout configured.
+
+This will typically result in a pipeline failure when the following sequence of events happen:
 
 1. A job acquires lock `lock-1`.
 2. Time passes by, the Pool Boy detects `lock-1` as stale and brings it back to the available pool.
@@ -161,5 +166,4 @@ Copyright 2018 Pix4D
 Note: there is no built-in help for git subtree, on the other hand the very good help is at https://github.com/git/git/blob/master/contrib/subtree/git-subtree.txt
 
 
-[Concourse pool-resource]: https://github.com/concourse/pool-resource
-[Pix4D pool-resource]: https://github.com/Pix4D/pool-resource
+[forked version of the Concourse pool-resource]: https://github.com/Pix4D/pool-resource