Go to https://github.com/logchange/logchange
CHANGELOG.md
is one of the most important files in a repository. It allows others to find out about
the most important changes in the project in short time.
To achieve this, CHANGELOG.md
should be created be in accordance with the rules, however there is no one
standard agreed by community.
Another big problem with CHANGELOG.md
is a problem with merge conflicts. Probably you, as a developer also
encounter it, when someone merged changes to CHANGELOG.md
before you.
To solve these problems, this maven plugin was created. It allows to keep a changelog style and reduce merge request conflicts by keeping every change
in a separate YAML file and generate CHANGELOG.md
during release.
This plugin is also helpful to create reliable release notes during your release process.
The convention is maintained according to the principles set out in the Keep a Changelog and with some additions as a result from experience in developing various types of projects.
The same problem with merge conflicts with CHANGELOG.md
was described by GitLab. LINK
The example project with this plugin usage you can find in example
directory.
Add a plugin to your pom.xml
. For multi-module projects with one CHANGELOG.md
add it in main pom.xml
.
<build>
<plugins>
<plugin>
<groupId>io.github.marwin1991</groupId>
<artifactId>keep-changelog-maven-plugin</artifactId>
<version>0.3.0</version>
</plugin>
</plugins>
</build>
Use this command from your terminal to create important directories and empty CHANGELOG.md
mvn keep-changelog:init
If you already had a CHANGELOG.md
file you can move it to changelog/archive.md
file. The name of the archive file have to start from archive
phrase (f.e. archive-1.0.0.md
).
After using init
command or just creating changelog/unreleased
directory your project is ready, and you can start
adding new changelog entries by creating YAML files.
IMPORTANT: If you develop on two main branches like f.e 1.1.X and 1.2.X do not merge 1.1.X branch to 1.2.X
before release otherwise YAML files will merge in one big version.
In future there is a plan to support unreleased*
directories names like unreleased-1.1
Adding new change is really simple, you can just add new YAML file to changelog/unreleased
directory and keep format
presented below. You can also use command to generate this file:
[TODO] - functionality not done yet
mvn keep-changelog:add
title: Test title
authors:
- nick: marwin1991
url: https://github.com/marwin1991
merge_request: 1
issues:
- 1
links: # links to external systems, like redmine something else
- name: TASK_NUMBER
url: https://www.google.pl
type: fixed # [added/changed/deprecated/removed/fixed/security]
important_notes:
- Update style.css on server during instalation 1
- configuration 2
- configuration 3
configuration: # information about changes in available application configuration
- type: database parameter
action: add # [add/update/delete]
key: simpleparam.name.enabled
default_value: true
description: Enables displying feature name
more_info: "You can put more information here, any text f.e !1 #1, even [link test](https://google.com)" #if you want to use # sign, yaml value must be a string inside ""
Keyword | Description |
---|---|
title |
Description of change that has been made. |
authors |
List of change's authors. |
merge_request |
The merge request's number which is adding this change. |
issues |
List of issues associated with this change. |
type |
Type of the change. |
links |
Any link to other project or external tool witch contains information about this change. |
important_notes |
Important notes, that has to be included in release. |
configurations |
Configration changes important during release. |
Everytime you want to generate CHANGELOG.md
you can use command:
mvn keep-changelog:generate
To prevent merge conflicts (it is idea of this project) generation should be done with use of CI/CD Tool on a main branch of a project.
[TODO] Create Docker image with this tool, that will be use in CI/CD Tool, so that not only java projects will be able to use it.
mvn keep-changelog:release
TODO
TODO
TODO
TODO
- add command to create archive-X.md from selected directory
- add tests
- add javadocs
- support
unreleased*
directories names likeunreleased-1.1