JarCastingChangelog Buildbreaker Maven Plugin
A Maven plugin that checks your changelog for changes that aren't tied to a version number.
Contents
- Reasoning
- Check and remedy for unreleased changes
- Integration and usage
- Examples
- Configuration options
- Understanding the RegEx
Reasoning
Changelogs should be in sync with the corresponding release: It is confusing for your users if the changelog does not reflect the latest changes. An obvious mistake are changes in your changelog labelled as "unreleased".
This Maven plugin checks that there are no more unreleased changes in your changelog and breaks build otherwise. It is intended to be used in your release build, since your changelog should have been finalised then.
Your changelog is expected to follow the format proposed by keepachangelog.com.
Check and remedy for unreleased changes
A CHANGELOG.md file has to be present in the project's root directory. An ## [Unreleased] section has to be present but it must be empty, i.e. no visible characters, but blank lines are allowed. If necessary, the filename and the regular expression used for checking can be configured.
If there are no unreleased changes, the build will silently continue. Otherwise the plugin will make the build fail. All you normally have to do then is to start a new section in your changelog for that current release and move all unreleased changes to that section.
Integration and usage
You can either run this plugin on demand, bind it to Maven's "verify" phase or integrate it with the Maven Release Plugin.
Call goal on-demand
You can always run the following without any preparation:
mvn com.github.peterwippermann.maven:changelog-buildbreaker-maven-plugin:check
Maven will download the plugin automatically and run its check goal. However, even when not binding the plugin to a certain Maven phase, it's a good practice to explicitly pin the plugin's version by declaring it in your build configuration (see below).
Bind this plugin to Maven's "verify" phase
<build>
<plugins>
<plugin>
<groupId>com.github.peterwippermann.maven</groupId>
<artifactId>changelog-buildbreaker-maven-plugin</artifactId>
<version>0.1.1</version>
<executions>
<execution>
<id>check-changelog-before-deploy</id>
<phase>verify</phase>
<goals>
<goal>check</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
Running mvn deploy will also include the verify phase and thus execute the check.
Caution: This check will then also affect your local development when running mvn install! So if you want to have your changelog checked for a release only, you can move this plugin execution to a dedicated Maven profile. This is also what we did in this plugin's own POM!
Integrate the check with the Maven Release Plugin
If you are using the Maven Release Plugin for releasing, you can easily have it execute the Changelog Buildbreaker Plugin in the preparation of the release.
- Add the Changelog Buildbreaker Plugin to your build configuration
- Bind the plugin to the Maven Release Plugin
<build>
<plugins>
<plugin>
<groupId>com.github.peterwippermann.maven</groupId>
<artifactId>changelog-buildbreaker-maven-plugin</artifactId>
<version>0.1.1</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-release-plugin</artifactId>
[...]
<configuration>
<preparationGoals>clean changelog-buildbreaker:check verify</preparationGoals>
<!-- Note that no GroupID is required and the shortname "changelog-buildbreaker" can be used -->
<!-- "clean verify" are the default goals of the release plugin and should be kept. -->
</configuration>
</plugin>
</plugins>
</build>
Now, when preparing a release with mvn release:prepare the changelog will also be checked.
Examples
In src/test/resources you find some examples of valid and invalid CHANGELOG files. The general rule is: The plugin raises an error if there is a section ## [Unreleased] that is NOT followed by another line starting with ##, regardless of blank lines in between.
Passing examples
## [Unreleased]
## [Unreleased]
## Another section
Failing examples
## [Unreleased]
- Fixed that mean bug
## [Unreleased]
### Added
- A cool feature
Configuration options
The following snippet illustrates the configuration parameters when referencing the plugin in your POM. The configuration values in the example are the defaults. So if you stick to the convention you don't have to set them.
<build>
<plugins>
<plugin>
<groupId>com.github.peterwippermann.maven</groupId>
<artifactId>changelog-buildbreaker-maven-plugin</artifactId>
[...]
<configuration>
<changelogFile>CHANGELOG.MD</changelogFile>
<encoding>UTF-8</encoding>
<unreleasedChangesPattern>(?:^|\\R)(?<section>##\\h*\\[Unreleased\\]\\h*)\\R(?:\\h*\\R)*(?<content>\\h*(?!##\\h*\\[)\\p{Graph}+.*)(?:$|\\R)</unreleasedChangesPattern>
</configuration>
</plugin>
</plugins>
</build>
Understanding the RegEx
Although the plugin only checks for an empty Unreleased section, the Regular Expression used is far from trivial:
(?:^|\\R)(?<section>##\\h*\\[Unreleased\\]\\h*)\\R(?:\\h*\\R)*(?<content>\\h*(?!##\\h*\\[)\\p{Graph}+.*)(?:$|\\R)
If you want to use your own, modified RegEx, here's what you need to know about the original version:
\\- In RegEx special characters are masked by a backslash\. However, in XML a backslash has to be escaped as well. Thus a double backslash\\has to be used in the XML configuration but not in the plugin's Java sources.(?:^|\\R)- The unreleased section's heading is preceded by a line break or even by the beginning of the file(?<section>##\\h*\\[Unreleased\\]\\h*)\\R- Locates the actual section heading "[Unreleased]". An arbitrary number of (horizontal) whitespaces are allowed at the beginning and the end. The match is assigned to a named group "section" and will be printed in the logs during plugin execution.(?:\\h*\\R)*- An arbitrary number of "empty lines", which may also include whitespaces.(?<content>\\h*(?!##\\h*\\[)\\p{Graph}+.*)- A named group "content", which matches any printable characters - except for a 2nd-order heading. That 2nd-order heading would be the latest release.(?:$|\\R)- The unreleased content is followed by a line break or end of file (EOF).- The two named groups section and content are optional. But if one of them is defined, in case of a match its content will be logged.