Document the release task.

Also adds sample alternate release workflow in sample.project.clj.

doc/DEPLOY.md

@@ -237,3 +237,83 @@ will eventually be automated through the use of a plugin.) The release
 will show up in OSS' releases repository immediately, and sync to Maven
 Central on the next cycle (~ 1-4 hours usually). 
 
+## Releasing Simplified
+
+Once you have your repositories and user credentials configured for deploying,
+much of the work involved in actually deploying a release version can be tedious
+and difficult to perform in a consistent fashion from one release to the next.
+To simplify the release process, there is a `lein release <version-name>` task
+where <version-name> can be refer to any of the standard Semantic Version
+levels, `:major`, `:minor`, or `:patch`. The simplification lies in the list of
+`:release-tasks` that get run on each call to `lein release <version-name>`. For
+example, suppose that your `project.clj` starts off as follows:
+
+```clojure
+(defproject leiningen "2.4.0-SNAPSHOT"
+```
+Using the default `:release-tasks` and the following command line:
+
+    $ lein release :patch
+
+The following events will happen:
+
+1. First, `leiningen` will assert that the current version control system
+   repository does not have any unstaged changes.
+
+2. Then, the `change` task is run to remove whatever qualifier is currently on
+   the version in `project.clj`. In this case, the top of `project.clj` should
+   look something like:  
+        ```clojure    
+(defproject leiningen "2.4.0"
+        ```
+3. `vcs` tasks will be run to commit this change and then tag the repository
+   with the `release` version number.
+
+4. The `deploy` task will be the same as if `lein deploy` had ben run from the
+   command line. **NOTE** This will require a valid "releases" entry either in
+   `:deploy-repositories` or `:repositories`
+
+5. The `change` task is run once more to "bump" the version number in
+   `project.clj`. Which semantic version level bumped is decided by the argument
+   passed to `lein release`, in this case :patch. Afterword, `project.clj` will
+   look something like:  
+        ```clojure
+(defproject leiningen "2.4.1-SNAPSHOT"
+        ```
+6. Finally, `vcs` tasks will be run once more to commit the new change to
+   `project.clj` and then push these two new commites to the default remote
+   repository.
+
+### Overriding the default `:release-tasks`
+
+The default list of tasks for `:release-tasks` is as follows:
+```clojure
+   :release-tasks [["vcs" "assert-committed"]
+                   ["change" "version"
+                    "leiningen.release/bump-version" "release"]
+                   ["vcs" "commit"]
+                   ["vcs" "tag"]
+                   ["deploy"]
+                   ["change" "version"
+                    "leiningen.release/bump-version" "leiningen.release/*level*"]
+                   ["vcs" "commit"]
+                   ["vcs" "push"]]
+```
+This `:release-tasks` value can be overridden in `project.clj`. An example might
+be a case in which you want the default workflow up to `lein deploy` but don't
+want to automatically bump the version in `project.clj`:
+```clojure
+  :release-tasks [["vcs" "assert-committed"]
+                  ["change" "version"
+                   "leiningen.release/bump-version" "release"]
+                  ["vcs" "commit"]
+                  ["vcs" "tag"]
+                  ["deploy"]]
+```
+Of course, `:release-tasks` doesn't have to look anything like the default, the
+default is just an assumed convention among most clojure projects using
+leiningen.
+
+`:release-tasks` is a vector in which every element is either a task name or a
+collection in which the first element is a task name and the rest are arguments
+to that task.

sample.project.clj

@@ -195,6 +195,20 @@
             ;; Nested vectors are supported for the "do" task
             ["do" "clean" ["test" ":integration"] ["deploy" "clojars"]]}
 
+  ;;; Custom Release Tasks
+  ;; By default `lein release` performs a series of tasks typical of the release
+  ;; process for many leiningen-managed projects. These tasks can be overridden
+  ;; using `:release-tasks` as follows:
+  :release-tasks [["vcs" "assert-committed"]
+                  ["change" "version"
+                   "leiningen.release/bump-version" "release"]
+                  ["vcs" "commit"]
+                  ["vcs" "tag"]
+                  ["deploy"]]
+  ;; This differs from the default `:release-tasks` behavior in that it doesn't
+  ;; go on to perform another `change version` or `vcs` task, instead leaving
+  ;; that up to the developer to do manually.
+
   ;;; Running Project Code
   ;; Normally Leiningen runs the javac and compile tasks before
   ;; calling any eval-in-project code, but you can override this with

src/leiningen/release.clj

@@ -53,9 +53,37 @@
 (defn ^{:subtasks []} release
   "Perform release tasks.
 
-TODO: document default :release-tasks and how to change them."
+The default list of release tasks is as follows:
+
+   :release-tasks [['vcs' 'assert-committed']
+                   ['change' 'version'
+                    'leiningen.release/bump-version' 'release']
+                   ['vcs' 'commit']
+                   ['vcs' 'tag']
+                   ['deploy']
+                   ['change' 'version'
+                    'leiningen.release/bump-version' 'leiningen.release/*level*']
+                   ['vcs' 'commit']
+                   ['vcs' 'push']]
+
+So the basic workflow here is change the version stored in project.clj, commit
+that change, tag this commit to with the release version indicated, deploy to
+the Maven release repository, then change to the next snapshot version in
+project.clj, commit that change, and push to the default remote version control
+repository.
+
+A key point to note is that this default set of :release-tasks requires a clean
+working directory as far as the current version control system is concerned.
+This ensures that the 'vcs commit' tasks will only save changes made to
+project.clj made by the 'change version' tasks.
+
+This behavior can be overridden by setting :release-tasks a vector in which
+every element is either a task name or a collection in which the first element
+is a task name and the rest are arguments to that task.
+
+The 'release' task takes a single argument which should be one of :major,
+:minor, or :patch to indicate which semantic versioning level to bump."
   [project level]
-  ;; TODO: how to propagate level arg to inc-version function? binding?
   (binding [*level* level]
     (doseq [task (:release-tasks project)]
       (let [[task-name & task-args] (if (vector? task) task [task])