dryewo / lein-changelog

A Leiningen plugin to automate changelog tasks.

lein-changelog

A Leiningen plugin to automate changelog tasks as part of lein release routine.

In support for Keep a Changelog initiative, relies on the changelog format proposed there.

Intended to be used as part of automated release procedure.

Usage

First, modify :plugins vector of your project.clj:

    :plugins [[lein-changelog "0.3.2"]]

Then add ["changelog" "release"] to :release-tasks in your project.clj:

  :release-tasks [... 
                  ["changelog" "release"]
                  ...]

If you have no :release-tasks key in your project.clj, please read more about custom release tasks and add it. Custom :release-tasks is necessary to automate changelog work.

IMPORTANT: the ["changelog" "release"] has to come after version bumping (["change" "version" ...]), because lein-changelog reads the version from project.clj.

Example :release-tasks (read more about this specific procedure here):

  :release-tasks [["vcs" "assert-committed"]
                  ["change" "version" "leiningen.release/bump-version"]
                  ["change" "version" "leiningen.release/bump-version" "release"]
                  ["changelog" "release"]
                  ["vcs" "commit"]
                  ["vcs" "tag"]
                  ["deploy"]
                  ["vcs" "push"]]

If you don't have CHANGELOG.md

Run this command to generate a dummy CHANGELOG.md file from template:

$ lein changelog init

Open the freshly generated CHANGELOG.md file and check its contents. You might want to correct the intro part and add some details to the the last released version section as well (it was generated from the latest git tag).

As you work on your project, add notable changes to ## [Unreleased] section with every commit you make.

If you already have CHANGELOG.md

If you didn't use lein changelog init to create it, make sure that it corresponds to the format.

When you are ready to release the next version, just run:

$ lein release :patch
# or
$ lein release :minor
# or
$ lein release :major

If you have configured :release-tasks as described above, lein changelog release will be called automatically to update CHANGELOG.md.

Explanation

When you run

$ lein release :<segment>

given that you have configured :release-tasks as described above, this plugin does the following (after the version is bumped in project.clj):

1. Reads contents of the CHANGELOG.md file.
2. Replaces ## [Unreleased] line with ## [X.Y.Z] - 2018-18-18,
   where X.Y.Z is the version from project.clj and 2018-18-18 is today's date.
3. Adds a new empty section with ## [Unreleased] title on top of the file.
4. Inserts links to GitHub diff UI to the end of the file:
   • [X.Y.Z] to show differences between this released version and previously released one.
   • [Unreleased] to show new changes since the latest released version.

Example:

Given this CHANGELOG.md:

blah-blah

## [Unreleased]
new-blah

## [0.1.1] - 2018-06-01
old-blah

## 0.1.0 - 2018-01-01
initial-blah

[0.1.1]: https://github.com/your-name/your-repo/compare/0.1.0...0.1.1
[Unreleased]: https://github.com/your-name/your-repo/compare/0.1.1...HEAD

After running lein release :minor, lein-changelog updates CHANGELOG.md like this (new version being released is 0.2.0):

blah-blah

## [Unreleased]

## [0.2.0] - 2018-18-18
new-blah

## [0.1.1] - 2018-06-01
old-blah

## 0.1.0 - 2018-01-01
initial-blah

[0.1.1]: https://github.com/your-name/your-repo/compare/0.1.0...0.1.1
[0.2.0]: https://github.com/your-name/your-repo/compare/0.1.1...0.2.0
[Unreleased]: https://github.com/your-name/your-repo/compare/0.2.0...HEAD

Changelog format

lein-changelog relies on the format described on Keep a Changelog, but the only required parts here are:

1. The file has to be named "CHANGELOG.md" and located in the root of the repository.
2. ## [Unreleased] line has be present in CHANGELOG.md exactly.
3. There has to be a line that looks like [Unreleased]: https://github.com/your-name/your-repo/compare/A.B.C...HEAD
   It will be copied and updated to create a diff link to the version currently being released (X.Y.Z) as well as to the new [Unreleased] diff.

If any of these lines are missing, the plugin will fail and exit with a non-zero code.

License

Copyright © 2018 Dmitrii Balakhonskii

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.

lein-changelog's Issues

Add support for other remote repositories (rather than only allowing github)

https://github.com/dryewo/lein-changelog/blob/master/src/leiningen/changelog.clj#L85

Provide an option to fail the release if there is nothing mentioned in the Unreleased section

This would be useful for supporting releases triggered by CI.

It's an additional quality gate: if nothing is added to changelog, it's probably not a good release.

User request: https://www.reddit.com/r/Clojure/comments/9m40bw/automating_changelog_tasks_with_leinchangelog/e7ef98u