Installation
All of this is in the documentation, but here's a friendly version.
First, grab the changelog jar
file and wrapper script. At the time of writing the current version is 4.1.0.
You can get both from Maven Central:
Download them with wget:
$ wget https://repo1.maven.org/maven2/com/io7m/changelog/com.io7m.changelog.cmdline/4.1.0/com.io7m.changelog.cmdline-4.1.0-main.jar $ wget https://repo1.maven.org/maven2/com/io7m/changelog/com.io7m.changelog.cmdline/4.1.0/com.io7m.changelog.cmdline-4.1.0-main.jar.asc $ wget https://repo1.maven.org/maven2/com/io7m/changelog/com.io7m.changelog.cmdline/4.1.0/com.io7m.changelog.cmdline-4.1.0.sh $ wget https://repo1.maven.org/maven2/com/io7m/changelog/com.io7m.changelog.cmdline/4.1.0/com.io7m.changelog.cmdline-4.1.0.sh.asc
I recommend verifying the signatures, for security reasons. You can skip this step if you like to live dangerously.
$ gpg --verify com.io7m.changelog.cmdline-4.1.0-main.jar.asc gpg: assuming signed data in 'com.io7m.changelog.cmdline-4.1.0-main.jar' gpg: Signature made Tue 12 Jan 2021 20:11:22 GMT gpg: using RSA key B32FA649B1924235A6F57B993EBE3ED3C53AD511 gpg: issuer "contact@io7m.com" gpg: using pgp trust model gpg: Good signature from "io7m.com (2021 maven-rsa-key) <contact@io7m.com>" [full] Primary key fingerprint: B32F A649 B192 4235 A6F5 7B99 3EBE 3ED3 C53A D511 gpg: binary signature, digest algorithm SHA512, key algorithm rsa3072 $ gpg --verify com.io7m.changelog.cmdline-4.1.0.sh.asc gpg: assuming signed data in 'com.io7m.changelog.cmdline-4.1.0.sh' gpg: Signature made Tue 12 Jan 2021 20:11:22 GMT gpg: using RSA key B32FA649B1924235A6F57B993EBE3ED3C53AD511 gpg: issuer "contact@io7m.com" gpg: using pgp trust model gpg: Good signature from "io7m.com (2021 maven-rsa-key) <contact@io7m.com>" [full] Primary key fingerprint: B32F A649 B192 4235 A6F5 7B99 3EBE 3ED3 C53A D511 gpg: binary signature, digest algorithm SHA512, key algorithm rsa3072
You need Java 11 or newer installed. Check that you have an up-to-date version:
$ java -version openjdk version "15.0.2" 2021-01-19 OpenJDK Runtime Environment (build 15.0.2+7) OpenJDK 64-Bit Server VM (build 15.0.2+7, mixed mode)
Now, place both the jar file and the sh script somewhere on your $PATH.
Personally, I use a $HOME/bin directory for this sort of thing.
$ echo $PATH /usr/local/sbin:/usr/local/bin:/usr/bin:/usr/bin/site_perl:/usr/bin/vendor_perl:/usr/bin/core_perl:/home/rm/bin $ mkdir -p $HOME/bin $ mv com.io7m.changelog.cmdline-4.1.0-main.jar $HOME/bin/ $ mv com.io7m.changelog.cmdline-4.1.0.sh $HOME/bin/changelog $ chmod +x $HOME/bin/changelog $ which changelog /home/rm/bin/changelog
The changelog wrapper script requires two environment variables, CHANGELOG_HOME
and CHANGELOG_JAR_NAME, to be defined. This allows the wrapper script to
find the jar file and run it. The CHANGELOG_HOME environment variable
tells the wrapper which directory it needs to look into for the jar file,
and the CHANGELOG_JAR_NAME variable specifies the name of the jar file.
$ export CHANGELOG_HOME="$HOME/bin" $ export CHANGELOG_JAR_NAME="com.io7m.changelog.cmdline-4.1.0-main.jar"
Now, you should be able to run changelog:
$ changelog
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/
Usage
See the documentation
for information on how to use the various changelog subcommands.
Editing Manually
Given that changelogs are simple XML files, it's possible to manually edit
them in any text editor. However, the changelog tool is very strict about
the format of changelogs, and will summarily reject any changelog that isn't
valid according to the published XSD schema.
Modern IDEs such as Intellij IDEA contain excellent support for real-time XML editing, including autocompletion of XML elements, and real-time schema errors as you type. This makes it very difficult to accidentally create an invalid changelog file.
First, download the schema file and save it somewhere. For this example,
I saved it in /tmp/schema.xsd, but you'll probably want to keep it somewhere
a little more permanent than your temporary directory!
$ wget https://raw.githubusercontent.com/io7m/changelog/develop/com.io7m.changelog.schema/src/main/resources/com/io7m/changelog/schema/schema.xsd $ mv schema.xsd /tmp
If you were to open an existing project that contained a README-CHANGES.xml
file that was created with the changelog tool at this point, you would see
something like this:
Note that the XML namespace is highlighted in red, because the IDE doesn't
know where to find the schema for that namespace. If you click the namespace
and then ALT+Enter, you'll get a drop-down menu that will allow you to set
up the schema file:
If you select "Manually setup external resource", you'll get a file picker
that you can use to select the schema.xsd file you downloaded earlier:
Now, when the schema file is selected, the XML namespace is no longer highlighted in red. Additionally, when you type, you'll be offered autocompletions of XML elements:
If you make mistakes editing the changelog file, you'll get nice validation errors as you type.
Here's "you tried to create an element that's not in the schema":
Here's "you typed garbage into the attributes of a known element":
Here's "you tried to reference an undeclared ticket system":
You can also, at any point, right-click the editor and select "Validate" to see the complete list of errors:
