Usage

3. Usage
- 3.1. Changelog
- 3.2. Initialization
- 3.3. Beginning Releases
- 3.4. Adding Changes
- 3.5. Finishing Releases
- 3.6. Formatting Changelogs

Changelog

The primary means by which users use the changelog package is via the changelog command-line tool. This section of the documentation provides a general usage guide for the command-line tool.

3.2

Initialization

1

The first step required in any project using changelog is to initialize an empty changelog. By convention, the changelog is called README-CHANGES.xml and lives in the root directory of the project. A changelog, if one doesn't already exist, can be created using the initialize command:

2

3.2.2 Initialization Example

$ changelog initialize
changelog: Main: ERROR: The following options are required: [--ticket-system-name], [--ticket-system-uri], [--project]

$ changelog initialize \
  --ticket-system-name com.github.io7m.example \
  --ticket-system-uri https://www.github.com/io7m/example/issues/ \
  --project com.io7m.example

$ changelog initialize \
  --ticket-system-name com.github.io7m.example \
  --ticket-system-uri https://www.github.com/io7m/example/issues/ \
  --project com.io7m.example
changelog: CLCommandInitialize: ERROR: File README-CHANGES.xml already exists

3

The changelog package allows for referencing tickets in external issue trackers in the recorded changes. This is accomplished by specifying one or more ticket systems, with exactly one ticket system being the default at any given time. Initializing a changelog requires specifying the default ticket system, but this ticket system can be changed on a per-release basis (as software projects often migrate to different issue tracking systems over their lifetime).

3.3

Beginning Releases

1

In order to start recording changes to the changelog, it's necessary to begin a release using the release-begin command. Once a release has begun, the release is open for modification (meaning that the version number can be changed, and that changes can be logged to the release). At most one release can be open at any given time.

2

3.3.2 release-begin Example

$ changelog release-begin

$ changelog release-begin
changelog: CLCommandReleaseBegin: ERROR: A release with version 4.0.0 is already open

3

The changelog package assumes that you're using Semantic Versioning for your project, and requires that you use simple three-part (major, minor, patch) version numbers. Upon attempting to begin a release, a version number will be selected for the new release if a number isn't specified with --version. The new release number will have the same major number as the previous release, with an incremented minor number and zero patch number. If there is no previous release, the package assumes the first release will be 1.0.0. The release-current command shows the version number of the current release, and whether or not the release is open for modification.

4

3.3.4 release-current Example

$ changelog release-current
changelog: CLCommandReleaseCurrent: ERROR: No current release exists

$ changelog release-begin
$ changelog release-current
1.0.0 (open)

$ changelog release-finish
$ changelog release-current
1.0.0 (closed)

5

The release-begin and release-finish commands are designed to work well in combination with gitflow-avh; on a git flow-enabled repo, developers would use the following sequence of commands during development:

6

3.3.6 Git Flow Example

$ git branch
develop

$ changelog release-begin --version 1.0.0
$ changelog release-current
1.0.0 (open)

...
<development work happens here>
...

$ changelog change-add --summary 'Implemented something'

...
<development work happens here>
...

$ changelog change-add --summary 'Implemented something else'

...
<development work happens here>
...

$ git flow release start 1.0.0
$ changelog release-finish
$ git flow release finish

...
<git flow asks for commit and merge messages>
<developer uses $ changelog write-plain to generate nice messages>

7

Essentially, the release-begin command is used when development begins on the develop branch. The developer makes numerous commits (possibly over the course of weeks or months), noting changes along the way with change-add. Then, when the user finally decides to actually produce a release, the release-finish command is used in combination with git flow release finish to mark the release as closed for modification.

3.4

Adding Changes

1

To record changes to the changelog, the change-add command should be used. The command accepts a mandatory --summary parameter that provides a very brief description (typically one line) of the change. The command also takes zero or more --ticket parameters that specify the IDs of the tickets affected by the change. Only an open release can be modified by the change-add.

2

3.4.2 change-add Example

$ changelog change-add --summary 'Broke something'

$ changelog change-add --summary 'Broke something new' --ticket 230 --ticket 2391

$ changelog release-finish

$ changelog change-add --summary 'Broke something else'
changelog: CLCommandChangeAdd: ERROR: The current release is not open for modification.

3.5

Finishing Releases

1

To finish a release, the release-finish command should be used. Once a release is finished, no more changes may be added to the release.

2

3.5.2 release-finish Example

$ changelog release-finish

$ changelog release-finish
changelog: CLCommandReleaseFinish: ERROR: No release is currently open

$ changelog add-change --summary 'Did something'
changelog: CLCommandChangeAdd: ERROR: The current release is not open for modification.

3.6

Formatting Changelogs

1

To produce a humanly-readable version of a changelog, various commands are available. The write-plain command produces a plain text log that is suitable for use in commit messages and other plain text media.

2

3.6.2 write-plain Example

$ changelog write-plain
Release: com.io7m.changelog 4.0.0
Change: (Backwards incompatible) Remove Vavr
Change: (Backwards incompatible) Modernize command-line interface with double-hyphen options
Change: Improve spacing in plain text log (Ticket: #11)
Change: Change command-line interface to explicit start and finish releases
Change: (Backwards incompatible) Completely redesign the changelog format and remove the use of XOM
Change: com.io7m.changelog.maven_plugin: (Backwards incompatible) Remove the Maven plugin
Change: (Backwards incompatible) Remove the com.io7m.jnull dependency
Change: (Backwards incompatible) Require JDK 9

$ changelog write-plain --show-dates true
2020-12-10 Release: com.io7m.changelog 4.0.0
2020-12-10 Change: (Backwards incompatible) Remove Vavr
2020-12-10 Change: (Backwards incompatible) Modernize command-line interface with double-hyphen options
2020-12-10 Change: Improve spacing in plain text log (Ticket: #11)
2020-12-10 Change: Change command-line interface to explicit start and finish releases
2017-11-11 Change: (Backwards incompatible) Completely redesign the changelog format and remove the use of XOM
2017-11-03 Change: com.io7m.changelog.maven_plugin: (Backwards incompatible) Remove the Maven plugin
2017-11-03 Change: (Backwards incompatible) Remove the com.io7m.jnull dependency
2017-11-03 Change: (Backwards incompatible) Require JDK 9

$ changelog write-plain --show-dates true --version 3.1.0
2017-10-15 Release: com.io7m.changelog 3.1.0
2017-10-15 Change: Rename project. Use the new primogenitor POM and 2017 project conventions.