logchange / logchange

πŸͺ΅ logchange is a tool which helps creating CHANGELOG by keeping one format and solving merge request conflicts problem by extraction of new CHANGELOG entries to seperate files

Home Page:https://logchange.dev

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

🌳 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.

🌲 When you create new merge/pull request and in the meantime you will release version, with old-fashioned CHANGELOG.md you have to remember, to move new changelog's entry up, to the new version section. With this tool you don't have to!

πŸͺ“ If your PO is against you to use this tool in your projects, don't worry... just ask him to do CHANGELOG.md by his own, and he will be the first one, who will ask you to use this tool. πŸ”₯

πŸͺ΅ To solve these problems, this project 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 tool is also helpful to create reliable release notes during your release process.

Reference

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

Usage

Maven Plugin

Starting

You can choose between two options:

  1. 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>dev.logchange</groupId>
            <artifactId>logchange-maven-plugin</artifactId>
            <version>1.4.0</version>
            <inherited>false</inherited> <!-- For multi module project -->
        </plugin>
    </plugins>
</build>
  1. You don't have to add anything to your pom.xml, just use all commands with groupId and full plugin name, like here:
mvn dev.logchange:logchange-maven-plugin:init 

⚠️⚠️ IMPORTANT ⚠️⚠️ For multi-module projects add --non-recursive to all executed commands! f.e.

mvn dev.logchange:logchange-maven-plugin:init --non-recursive

After choosing one of the options, how you prefer run this plugin, you can start using plugin as follows. Use this command from your terminal to create important directories and empty CHANGELOG.md

mvn logchange: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 (stored in unreleased directory) will merge in one big version (because all files from both versions will be in the same directory). In the future, if there will be a need, there is a plan to support unreleased* directories names like unreleased-1.1

Adding new change

Adding new change is really simple, you can just add new YAML file to changelog/unreleased directory and keep format presented below, or you can use command to generate this file, this one will guide you through whole process:

mvn logchange:add

In other hand, if you would like to just generate an empty file, with some default strings, you can use:

mvn logchange:add -Dempty -DfileName=000001-some-name.yml

YAML format

# This file is used by logchange tool to generate CHANGELOG.md 🌳 πŸͺ“ => πŸͺ΅
# Visit https://github.com/logchange/logchange and leave a star 🌟
# More info about configuration you can find https://github.com/logchange/logchange#yaml-format ⬅️
title: Test title
authors:
  - name: Peter
    nick: marwin1991
    url: https://github.com/marwin1991
merge_requests:
  - 1
issues:
  - 1
links: # links to different project's issue or external systems, like jira or redmine
  - name: TASK_NUMBER
    url: https://www.google.pl
type: fixed # [added/changed/deprecated/removed/fixed/security/dependency_update/other]
important_notes:
  - Update style.css on server during instalation 1
configurations: # 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_requests The merge requests' numbers which are 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 Configurations changes important during release.
configurations.type Type of configuration method, f.e via file application.properties or system environment's variables
configurations.action Define if configuration method was added (add) / updated (update) / deleted (delete)
configurations.key A key for configuration property
configurations.default_value Default value for configuration property
configurations.description Description of configuration property
configurations.more_info Here you can add anything even links (keep markdown format)

Example usage

Configuration

You can configure this plugin via logchange-config.yml file in changelog directory.

Copy following section as default config.

# This file configures logchange tool 🌳 πŸͺ“ => πŸͺ΅ 
# Visit https://github.com/logchange/logchange and leave a star 🌟 
# More info about configuration you can find https://github.com/logchange/logchange#configuration 
changelog:
  heading: Some information that will be display in the top of CHANGELOG.md
  labels:
    unreleased: unreleased
    important_notes: Important notes
    types:
      added: Added
      changed: Changed
      deprecated: Deprecated
      removed: Removed
      fixed: Fixed
      security: Security
      dependency_update: Dependency update
      other: Other
      number_of_changes:
        singular: change
        plural: changes
    configuration:
      heading: Configuration changes
      type: Type
      actions:
        add: Added
        delete: Deleted
        update: Updated
      with_default_value: with default value
      description: Description

Generating CHANGELOG.md

Everytime you want to generate CHANGELOG.md you can use command:

mvn logchange:generate

To prevent merge conflicts (it is idea of this project) generation of CHANGELOG.md should be done with use of CI/CD Tool on a main branch of a project during release.

Creating release (from unreleased directory)

This command is the preferred to create release and generates CHANGELOG.md (One of these command steps is to call the generate command). During release all files from unreleased directory are moved to v.X.X.X where X.X.X is the version from pom.xml. After moving files, command create file release-date.txt with current date, then generation of CHANGELOG.md and versions summaries is done.

mvn logchange:release

Generating changes.xml for maven-changes-plugin

Along with CHANGELOG.md there is also the option of generating Maven's changes.xml. To enable the option, add the parameter ChangesXml. To specify a different name, also add the parameter outputFileXml. At the moment archives are not supported, rather changes.xml will only contain the releases generated by this plugin.

mvn logchange:release -DchangesXml

For custom file name, add -DoutputFileXml=CustomName.xml

mvn logchange:release -DchangesXml -DoutputFileXml=CustomName.xml

CHANGELOG.md structure overview

TODO

Versions summaries

During release version-summary.md is created, it is a file that contains current version changelog entries. You can see example here.

This feature is really useful during creating releases on GitHub or GitLab, you can just attach the content of this file as release notes.

Archives

If your project already contains some CHANGELOG.md you don't have to rewrite it to yml. Only what have to do is to move it to changelog directory and rename it to archive.md or archiveXXXX.md where XXXX is anything you want f.e. -2.0.0.

⚠️⚠️ IMPORTANT ⚠️⚠️ archive-XXX.md has to be in changelog directory (changelog/archive-1.3.6.md) do not add any sub directories.

Quote or not to quote ?

According to the official YAML specification one should:

  • Whenever applicable use the unquoted style since it is the most readable.
  • Use the single-quoted style (') if characters such as " and \ are being used inside the string to avoid escaping them and therefore improve readability.
  • Use the double-quoted style (") when the first two options aren't sufficient, i.e. in scenarios where more complex line breaks are required or non-printable characters are needed.

TODO:

  • add command to create archive-X.md from selected directory
  • add javadocs
  • support unreleased* directories names like unreleased-1.1
  • 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.

Development

  1. Java installed.
  2. mvn as a command in your terminal(needed for integration tests).

About

πŸͺ΅ logchange is a tool which helps creating CHANGELOG by keeping one format and solving merge request conflicts problem by extraction of new CHANGELOG entries to seperate files

https://logchange.dev

License:Apache License 2.0


Languages

Language:Java 98.9%Language:Shell 1.1%