Uploaded image for project: 'Log4j 2'
  1. Log4j 2
  2. LOG4J2-3628

Migrate from maven-changes-plugin to a merge-conflict-free Markdown-based solution



    • Story
    • Status: Closed
    • Major
    • Resolution: Fixed
    • None
    • 2.20.0
    • None
    • None


      As of date, Log4j project keeps its changelog using maven-changelog-plugin.
      In a nutshell, developers register their entries to changes.xml and maven-changelog-plugin generates the report during Maven site phase.
      This approach has certain drawbacks:

      • maven-changelog-plugin hasn't been updated since 2016-10-29
      • maven-changelog-plugin doesn't allow text style formatting (e.g., code blocks)
      • maven-changelog-plugin doesn't allow an introduction paragraph. Everything needs to be a ticket; it is not possible to enhance the changelog of a release with "This release has mostly focused on bug fixes, yet we also shipped this awesome feature, ..." We work around this shortcoming via RELEASE-NOTES.md, which contradicts with the purpose of this plugin.
      • maven-changelog-plugin doesn't generate a Markdown-formatted release note where one can simply copy paste to, say, a GitHub release. Developers manually duplicate its efforts in RELEASE-NOTES.md.
      • maven-changelog-plugin source changes.xml constantly creates merge conflicts

      I propose to replace maven-changelog-plugin and changes.xml with the following merge-conflict-free Markdown-based solution:

      1. The changelogs of the released versions will be kept in changelogs/<yyyyMMdd>-<version>.md files (e.g., changelogs/20220223-2.17.2.md)
      2. changelogs/<yyyyMMdd>-<version>.md files will be structured as described in keep a changelog, where tickets are grouped in following types: Added, Changed, Deprecated, Removed, Fixed, and Security
      3. changelogs/index.md will keep an index of all changelogs/<yyyyMMdd>-<version>.md files
      4. The changelog of the unreleased version will be kept in changelogs/unreleased directory
        1. changelogs/unreleased/<type>_<description>.md files will be used to register changes: Added_JTL_Jackson_fallback_support.md, Removed_SLF4J_1.8_bridge.md, etc. The contents of these files must be a single-line Markdown, since it will later be used in a Markdown bullet list.
        2. changelogs/unreleased/template.md will contain the Markdown file that will be used to render the final changelog just before a release. <div id="Tickets"/> will be replaced with a Markdown bullet list containing the files in the folder.
        3. changelogs/index.md and changelogs/<yyyyMMdd>-<version>.md files will be symlinked under src/site/markdown/changelogs directory
      5. bin/generate-changelogs.sh script will perform the following tasks:
        1. generating a changelogs/<yyyyMMdd>-<version>.md from the contents of changelogs/unreleased
        2. removing all changelogs/unreleased/<type>_<description>.md files
        3. generating changelogs/index.md again

      How does a changelogs/unreleased/template.md file look like?

      The Apache Log4j 2 team is pleased to announce the Log4j <span id="revision"/> release!
      This release primarily contains bug fixes and minor enhancements.
      <div id="Tickets"/>

      What shall I do when I am about to commit a change?

      Add a changelogs/unreleased/<type>_<description>.md file along with your changes.

      What shall I do when I am about to make a new Log4j release?

      Update the version in the root pom.xml, call bin/generate-changelogs.sh, review and commit changes.
      Now you can proceed with ./mvnw deploy.

      What about the current changes.xml?

      We will migrate all of its contents to changelogs/<yyyyMMdd>-<version>.md via a simple script and remove changes.xml.




            vy Volkan Yazici
            vy Volkan Yazici
            0 Vote for this issue
            4 Start watching this issue