Skip to content

Commit

Permalink
Reword a few things in deploy.md.
Browse files Browse the repository at this point in the history
  • Loading branch information
@technomancy
technomancy committed May 27, 2014
1 parent 3e6b8a1 commit 88f2d34
Show file tree
Hide file tree
Showing 3 changed files with 104 additions and 100 deletions.
194 changes: 99 additions & 95 deletions doc/DEPLOY.md
View file
Expand Up @@ -44,17 +44,6 @@ projects may also be specified in the `:user` profile in `~/.lein/profiles.clj`:
{:user {:deploy-repositories [["internal" "http://blueant.com/archiva/internal"]]}}
```

Additionally, it is possible to alias repositories by specifiing a string value
with the name of another repositoriy in `:deploy-repositories`:

```clj
{:user {:deploy-repositories [["internal" "http://blueant.com/archiva/internal"]
["releases" "internal"]]}}
```

In this example the command line `lein deploy releases` is a synonym for `lein
deploy internal`.

### Non-standard Repository Protocols

If you are deploying to a repository that doesn't use one of the
Expand Down Expand Up @@ -174,9 +163,105 @@ appropriately, you can deploy to it:

$ lein deploy [repository-name]

If the project's current version is a `SNAPSHOT`, it will default to
deploying to the `snapshots` repository; otherwise it will default to
`releases`.
If the project's current version is a `SNAPSHOT`, it will default to deploying
to the `"snapshots"` repository; otherwise it will default to `"releases"`. In
order to make `lein deploy` with no argument target Clojars, include this in
your `project.clj`:

```clj
{:deploy-repositories [["releases" "clojars"]]}
```

You can use this to alias any `:repositories` entries; Clojars is just the most
common use case.

## 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 [$LEVEL]` task
where `$LEVEL` 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`. 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. The `change` task is run to remove whatever qualifier is currently on
the version in `project.clj`. In this case, `project.clj` should
look something like:
```clojure
(defproject leiningen "2.4.0" ...)
```

2. `vcs` tasks will be run to commit this change and then tag the repository
with the `release` version number.

3. 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`

4. 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" ...)
```

5. Finally, `vcs` tasks will be run once more to commit the new change to
`project.clj` and then push these two new commits to the default remote
repository.

The release process will fail if there are uncommitted changes.

### Overriding the default `:release-tasks`

You can use the `lein-pprint` plugin to see the default value of `:release-tasks`:

```
$ lein pprint :release-tasks
[["vcs" "assert-committed"]
["change" "version" "leiningen.release/bump-version" "release"]
["vcs" "commit"]
["vcs" "tag"]
["deploy"]
["change" "version" "leiningen.release/bump-version"]
["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"]]
```

The `:release-tasks` vector should have every element be either a task name or a
collection in which the first element is a task name and the rest are arguments
to that task, just like `:prep-tasks` or `:aliases` entries.

Of course, `:release-tasks` doesn't have to look anything like the
default, the default is just an assumed convention among most Clojure
libraries using Leiningen. Applications will have different requirements
that are varied enough that Leiningen doesn't attempt to support them
out of the box.

## Deploying to Maven Central

Expand Down Expand Up @@ -247,84 +332,3 @@ close and release/promote your staged repository. (This manual step
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.
1 change: 1 addition & 0 deletions leiningen-core/src/leiningen/core/project.clj
View file
Expand Up @@ -186,6 +186,7 @@
:clean-targets ^:top-displace [:target-path]
;; TODO: remove :top-displace for :prep-tasks in 3.0
:prep-tasks ^:top-displace ["javac" "compile"]
;; If these change, be sure to update release docstring and DEPLOY.md
:release-tasks ^:top-displace [["vcs" "assert-committed"]
["change" "version"
"leiningen.release/bump-version" "release"]
Expand Down
9 changes: 4 additions & 5 deletions src/leiningen/release.clj
View file
Expand Up @@ -66,11 +66,10 @@ The default list of release tasks is as follows:
[\"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.
First change the version stored in project.clj, then 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.
Expand Down

0 comments on commit 88f2d34

Please sign in to comment.