TITLE | Changelog User Manual 5.0.0-beta0002 |
IDENTIFIER | 77a12e7a-9a2b-41f8-90e4-b11e5311fda0 |
DESCRIPTION | User documentation for the com.io7m.changelog package. |
SOURCE | https://www.io7m.com/software/changelog/ |
DATE | 2021-01-12 |
File | Description |
---|---|
com.io7m.changelog.cmdline-5.0.0-beta0002-main.jar | The main executable jar. |
com.io7m.changelog.cmdline-5.0.0-beta0002-main.jar.asc | The PGP signature of the executable jar. |
com.io7m.changelog.cmdline-5.0.0-beta0002.sh | The main command-line wrapper. |
com.io7m.changelog.cmdline-5.0.0-beta0002.sh.asc | The PGP signature of the command-line wrapper. |
$ gpg --verify com.io7m.changelog.cmdline-5.0.0-beta0002-main.jar.asc $ gpg --verify com.io7m.changelog.cmdline-5.0.0-beta0002.sh.asc
$ java -jar com.io7m.changelog.cmdline-5.0.0-beta0002-main.jar version changelog 5.0.0-beta0002
$ mkdir $HOME/bin $ cp com.io7m.changelog.cmdline-5.0.0-beta0002-main.jar $HOME/bin/ $ export PATH="${PATH}:${HOME}/bin" $ export CHANGELOG_HOME="$HOME/bin" $ export CHANGELOG_JAR_NAME="com.io7m.changelog.cmdline-5.0.0-beta0002-main.jar" $ changelog version changelog 5.0.0-beta0002 $ which changelog /home/example/bin/changelog
$ 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
$ changelog release-begin $ changelog release-begin changelog: CLCommandReleaseBegin: ERROR: A release with version 4.0.0 is already open
$ 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)
$ 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>
$ 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.
$ 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.
$ 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.
changelog: Main: INFO: Usage: changelog [options] [command] [command options] Options: --verbose Set the minimum logging verbosity level. Default: info Possible Values: [trace, debug, info, warn, error] Use the "help" command to examine specific commands: $ changelog help help. Command-line arguments can be placed one per line into a file, and the file can be referenced using the @ symbol: $ echo help > file.txt $ echo help >> file.txt $ changelog @file.txt Commands: change-add Add a change to the current release. help Show detailed help messages for commands. initialize Initialize the changelog. release-begin Start the development of a new release. release-current Display the version number of the current release. release-finish Finish a release. release-set-version Set the version number of the current release. version Retrieve the program version. write-atom Generate an atom feed. write-plain Generate a plain text log. write-xhtml Generate an XHTML log. Documentation: https://www.io7m.com/software/changelog/documentation/
Name | Description |
---|---|
trace | All messages greater than or equal to trace level (highest) |
debug | All messages greater than or equal to debug level |
info | All messages greater than or equal to info level |
warn | All messages greater than or equal to warn level |
error | All messages greater than or equal to error level |
$ (cat <<EOF --file README-CHANGES.xml --ticket-system-name com.github.io7m.changelog.test --ticket-system-uri https://www.github.com/io7m/changelog/issues/ --project com.io7m.changelog.test EOF ) > args.txt $ changelog initialize @args.txt
Parameter | Type | Required | Description |
---|---|---|---|
--file | Path | false | Set the name of the changelog file. |
--verbose | Log Level | false | Set the minimum logging verbosity level. |
--incompatible | Boolean | false | true if the change is backwards-incompatible. |
--module | String | false | The name of the affected module, if any. |
--summary | String | true | The summary of the change. |
--ticket | String | false | The ticket affected by the change. May be specified multiple times. |
$ 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.
Parameter | Type | Required | Description |
---|---|---|---|
--verbose | Log Level | false | Set the minimum logging verbosity level. |
$ changelog help help changelog: Main: INFO: Usage: help [options] command Options: --verbose Set the minimum logging verbosity level. Default: info Possible Values: [trace, debug, info, warn, error] The "help" command, executed without arguments, shows the names of all commands including the names and types of all of their parameters. The "help" command can also be passed the name of a command. Commands may include extended help messages such as the one you are reading right now. Example: changelog help help $ changelog help initialize changelog: Main: INFO: Usage: initialize [options] Options: --file The changelog file Default: README-CHANGES.xml * --project The project name * --ticket-system-name The name of the primary ticket system * --ticket-system-uri The URI of the primary ticket system --verbose Set the minimum logging verbosity level. Default: info Possible Values: [trace, debug, info, warn, error] The initialize command initializes an empty changelog.
Parameter | Type | Required | Description |
---|---|---|---|
--file | Path | false | Set the name of the changelog file. |
--verbose | Log Level | false | Set the minimum logging verbosity level. |
--ticket-system-name | Ticket System ID | true | Set the unique ID of the ticket system. |
--ticket-system-uri | Ticket System URI | true | Set the URI of the ticket system. |
--project | Project Name | true | Set the name of the project. |
$ changelog version changelog 4.0.0
Parameter | Type | Required | Description |
---|---|---|---|
--file | Path | false | Set the name of the changelog file. |
--verbose | Log Level | false | Set the minimum logging verbosity level. |
--ticket-system | Ticket System ID | false | The ticket system used for this release. |
--version | Version | true | The release version. |
$ changelog release-begin $ changelog release-begin changelog: CLCommandReleaseBegin: ERROR: A release with version 4.0.0 is already open
Parameter | Type | Required | Description |
---|---|---|---|
--file | Path | false | Set the name of the changelog file. |
--verbose | Log Level | false | Set the minimum logging verbosity level. |
$ 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)
Parameter | Type | Required | Description |
---|---|---|---|
--file | Path | false | Set the name of the changelog file. |
--verbose | Log Level | false | Set the minimum logging verbosity level. |
--version | Version | true | The release version. |
$ changelog release-current 0.9.2 (open) $ changelog release-set-version --version 1.0.0 $ changelog release-current 1.0.0 (open)
Parameter | Type | Required | Description |
---|---|---|---|
--file | Path | false | Set the name of the changelog file. |
--verbose | Log Level | false | Set the minimum logging verbosity level. |
--version | Version | true | The release version. |
$ 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.
Parameter | Type | Required | Description |
---|---|---|---|
--verbose | Log Level | false | Set the minimum logging verbosity level. |
$ changelog version changelog 4.0.0
Parameter | Type | Required | Description |
---|---|---|---|
--file | Path | false | Set the name of the changelog file. |
--verbose | Log Level | false | Set the minimum logging verbosity level. |
--author-email | String | true | The author email address used in the RSS feed. |
--author-name | String | true | The author name used in the RSS feed. |
--title | String | true | The title of the RSS feed. |
--uri | URI | true | The URI of the RSS feed. |
$ changelog write-atom \ --author-email someone@example.com \ --author-name 'Someone' \ --title 'A Feed' \ --uri 'https://www.example.com/atom.feed' <?xml version="1.0" encoding="UTF-8"?> <a:feed xmlns:a="http://www.w3.org/2005/Atom"> <a:author> <a:name>Someone</a:name> <a:email>someone@example.com</a:email> </a:author> <a:id>https://www.example.com/atom.feed</a:id> <a:title>A Feed</a:title> <a:updated>2020-12-10T19:42:05+00:00</a:updated> <a:entry> <a:id>4.0.0</a:id> <a:updated>2020-12-10T00:00:00+00:00</a:updated> <a:published>2020-12-10T00:00:00+00:00</a:published> <a:title>com.io7m.changelog 4.0.0 released</a:title> <a:content type="text">com.io7m.changelog 4.0.0 released</a:content> </a:entry> <a:entry> <a:id>3.1.0</a:id> <a:updated>2017-10-15T00:00:00+00:00</a:updated> <a:published>2017-10-15T00:00:00+00:00</a:published> <a:title>com.io7m.changelog 3.1.0 released</a:title> <a:content type="text">com.io7m.changelog 3.1.0 released</a:content> </a:entry> <a:entry> <a:id>3.0.3</a:id> <a:updated>2017-01-10T00:00:00+00:00</a:updated> <a:published>2017-01-10T00:00:00+00:00</a:published> <a:title>com.io7m.changelog 3.0.3 released</a:title> <a:content type="text">com.io7m.changelog 3.0.3 released</a:content> </a:entry> <a:entry> <a:id>3.0.2</a:id> <a:updated>2017-01-10T00:00:00+00:00</a:updated> <a:published>2017-01-10T00:00:00+00:00</a:published> <a:title>com.io7m.changelog 3.0.2 released</a:title> <a:content type="text">com.io7m.changelog 3.0.2 released</a:content> </a:entry> <a:entry> <a:id>3.0.1</a:id> <a:updated>2016-12-21T00:00:00+00:00</a:updated> <a:published>2016-12-21T00:00:00+00:00</a:published> <a:title>com.io7m.changelog 3.0.1 released</a:title> <a:content type="text">com.io7m.changelog 3.0.1 released</a:content> </a:entry> <a:entry> <a:id>3.0.0</a:id> <a:updated>2016-12-21T00:00:00+00:00</a:updated> <a:published>2016-12-21T00:00:00+00:00</a:published> <a:title>com.io7m.changelog 3.0.0 released</a:title> <a:content type="text">com.io7m.changelog 3.0.0 released</a:content> </a:entry> <a:entry> <a:id>2.1.2</a:id> <a:updated>2016-05-06T00:00:00+00:00</a:updated> <a:published>2016-05-06T00:00:00+00:00</a:published> <a:title>com.io7m.changelog 2.1.2 released</a:title> <a:content type="text">com.io7m.changelog 2.1.2 released</a:content> </a:entry> <a:entry> <a:id>2.1.1</a:id> <a:updated>2015-08-22T00:00:00+00:00</a:updated> <a:published>2015-08-22T00:00:00+00:00</a:published> <a:title>com.io7m.changelog 2.1.1 released</a:title> <a:content type="text">com.io7m.changelog 2.1.1 released</a:content> </a:entry> <a:entry> <a:id>2.1.0</a:id> <a:updated>2014-04-19T00:00:00+00:00</a:updated> <a:published>2014-04-19T00:00:00+00:00</a:published> <a:title>com.io7m.changelog 2.1.0 released</a:title> <a:content type="text">com.io7m.changelog 2.1.0 released</a:content> </a:entry> <a:entry> <a:id>2.0.0</a:id> <a:updated>2014-04-17T00:00:00+00:00</a:updated> <a:published>2014-04-17T00:00:00+00:00</a:published> <a:title>com.io7m.changelog 2.0.0 released</a:title> <a:content type="text">com.io7m.changelog 2.0.0 released</a:content> </a:entry> <a:entry> <a:id>1.0.0</a:id> <a:updated>2012-03-15T00:00:00+00:00</a:updated> <a:published>2012-03-15T00:00:00+00:00</a:published> <a:title>com.io7m.changelog 1.0.0 released</a:title> <a:content type="text">com.io7m.changelog 1.0.0 released</a:content> </a:entry> </a:feed>
Parameter | Type | Required | Description |
---|---|---|---|
--file | Path | false | Set the name of the changelog file. |
--verbose | Log Level | false | Set the minimum logging verbosity level. |
--version | Version | false | The release version. |
--count | Integer | false | The number of releases to show. |
--show-dates | Boolean | false | Show the date of each change. |
$ 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.
Parameter | Type | Required | Description |
---|---|---|---|
--file | Path | false | Set the name of the changelog file. |
--verbose | Log Level | false | Set the minimum logging verbosity level. |
--version | Version | false | The release version. |
--count | Integer | false | The number of releases to show. |
$ changelog write-xhtml <?xml version="1.0" encoding="UTF-8" standalone="no"?> <table class="changelog" summary="Changes for project com.io7m.changelog" xmlns="http://www.w3.org/1999/xhtml"> <tr> <td>2020-12-10</td> <td>Release: com.io7m.changelog 4.0.0</td> </tr> <tr> <td>2017-11-03</td> <td>Change: (Backwards incompatible) CModuleName{value=com.io7m.changelog.maven_plugin}: Remove the Maven plugin</td> </tr> <tr> <td>2017-11-03</td> <td>Change: (Backwards incompatible) Remove the com.io7m.jnull dependency</td> </tr> <tr> <td>2017-11-03</td> <td>Change: (Backwards incompatible) Require JDK 9</td> </tr> <tr> <td>2017-11-11</td> <td>Change: (Backwards incompatible) Completely redesign the changelog format and remove the use of XOM</td> </tr> <tr> <td>2020-12-10</td> <td>Change: (Backwards incompatible) Remove Vavr</td> </tr> <tr> <td>2020-12-10</td> <td>Change: (Backwards incompatible) Modernize command-line interface with double-hyphen options</td> </tr> <tr> <td>2020-12-10</td> <td> Change: Improve spacing in plain text log (tickets: <a href="https://www.github.com/io7m-com/changelog/issues/11">11</a> ) </td> </tr> <tr> <td>2020-12-10</td> <td>Change: Change command-line interface to explicit start and finish releases</td> </tr> <tr> <td>2017-10-15</td> <td>Release: com.io7m.changelog 3.1.0</td> </tr> <tr> <td>2017-10-15</td> <td>Change: Rename project. Use the new primogenitor POM and 2017 project conventions.</td> </tr> <tr> <td>2017-01-10</td> <td>Release: com.io7m.changelog 3.0.3</td> </tr> <tr> <td>2017-01-10</td> <td> Change: Fix printing of version numbers in report generation. (tickets: <a href="https://www.github.com/io7m-com/changelog/issues/3">3</a> ) </td> </tr> <tr> <td>2017-01-10</td> <td>Release: com.io7m.changelog 3.0.2</td> </tr> <tr> <td>2017-01-10</td> <td> Change: Fix date formatting in report generation. (tickets: <a href="https://www.github.com/io7m-com/changelog/issues/2">2</a> ) </td> </tr> <tr> <td>2016-12-21</td> <td>Release: com.io7m.changelog 3.0.1</td> </tr> <tr> <td>2016-12-21</td> <td>Change: Fix the command line frontend onejar configuration.</td> </tr> <tr> <td>2016-12-21</td> <td>Release: com.io7m.changelog 3.0.0</td> </tr> <tr> <td>2016-12-21</td> <td>Change: (Backwards incompatible) The package now requires Java 8.</td> </tr> <tr> <td>2016-12-21</td> <td>Change: The published artifacts are now OSGi bundles.</td> </tr> <tr> <td>2016-12-21</td> <td>Change: (Backwards incompatible) Consistently use com.io7m.changelog.* everywhere (some packages were rooted at com.io7m.changelogs).</td> </tr> <tr> <td>2016-12-21</td> <td>Change: (Backwards incompatible) Replace most of the API with Immutables.org generated types.</td> </tr> <tr> <td>2016-12-21</td> <td>Change: Add a command-line frontend.</td> </tr> <tr> <td>2016-05-06</td> <td>Release: com.io7m.changelog 2.1.2</td> </tr> <tr> <td>2016-05-06</td> <td>Change: Update site links and POM metadata</td> </tr> <tr> <td>2015-08-22</td> <td>Release: com.io7m.changelog 2.1.1</td> </tr> <tr> <td>2015-08-22</td> <td>Change: Migrate to GitHub.</td> </tr> <tr> <td>2014-12-03</td> <td>Change: Fix javadoc comments for Java 8's doclint.</td> </tr> <tr> <td>2014-12-03</td> <td>Change: Ensure source jars for unit tests are created.</td> </tr> <tr> <td>2014-04-19</td> <td>Release: com.io7m.changelog 2.1.0</td> </tr> <tr> <td>2014-04-19</td> <td>Change: Add Maven report plugin.</td> </tr> <tr> <td>2014-04-19</td> <td>Change: Add simple Atom feed generator.</td> </tr> <tr> <td>2014-04-17</td> <td>Release: com.io7m.changelog 2.0.0</td> </tr> <tr> <td>2014-04-17</td> <td>Change: Allow for zero or more releases in a file.</td> </tr> <tr> <td>2014-04-17</td> <td>Change: Do not allow xml:id on changelogs.</td> </tr> <tr> <td>2014-04-17</td> <td>Change: Allow multiple tickets per changelog item.</td> </tr> <tr> <td>2014-04-17</td> <td>Change: Redevelop package in Java, eliminate XSLT stylesheets.</td> </tr> <tr> <td>2014-04-17</td> <td>Change: (Backwards incompatible) Change schema URI and increment version to 2.0.0</td> </tr> <tr> <td>2012-03-15</td> <td>Release: com.io7m.changelog 1.0.0</td> </tr> <tr> <td>2012-03-15</td> <td>Change: Initial release.</td> </tr> </table>