[ https://issues.apache.org/jira/browse/LOG4J2-3628?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17631243#comment-17631243 ]
Ralph Goers commented on LOG4J2-3628: ------------------------------------- Part of this description is inaccurate/incomplete. # Maven changes plugin DOES generate release notes (RELEASE-NOTES.md) which DOES support a template - announcement.vm - which I regularly modify for releases. a. RELEASE-NOTES.md is never manually edited. # We do NOT use the maven-changelog-plugin. We use the maven-changes-plugin. Interestingly, it also supports GitHub issues. a. It has not had a release since 2016 b. It has been updated as recently as this year. # This proposal switches from using a structured definition where the changes are used for multiple purposes to one that is hand created. Note that there is nothing about this that prevents merge conflicts. Everywhere we get a merge conflict now in changes.xml the same would occur with this approach. Merge conflicts happen when two people modify the same part of a file, which is extremely likely when updating a changes file, no matter what format it is in. In short, the ONLY benefits I see to this are 1) it is not tied to the site plugin and 2) it allows some text to be added to the top of the changes page. I am quite sure we could fine a way to add text to the page if we really need it (no one has ever requested it). Also, mvn changes:report will generate the changes report without using the site plugin. So neither of these benefits are super important in my view. > Migrate from maven-changes-plugin to a merge-conflict-free Markdown-based > solution > ---------------------------------------------------------------------------------- > > Key: LOG4J2-3628 > URL: https://issues.apache.org/jira/browse/LOG4J2-3628 > Project: Log4j 2 > Issue Type: Story > Reporter: Volkan Yazici > Priority: Major > Fix For: 2.20.0 > > > As of date, Log4j project keeps its changelog using > [maven-changelog-plugin|https://maven.apache.org/plugins/maven-changes-plugin/]. > In a nutshell, developers register their entries to {{changes.xml}} and > {{maven-changelog-plugin}} generates [the > report|https://logging.apache.org/log4j/2.x/changes-report.html] 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|https://github.com/apache/logging-log4j2/releases]. 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: > # The changelogs of the *released* versions will be kept in > {{changelogs/<yyyyMMdd>-<version>.md}} files (e.g., > {{{}changelogs/20220223-2.17.2.md{}}}) > # {{changelogs/<yyyyMMdd>-<version>.md}} files will be structured as > described in [keep a changelog|https://keepachangelog.com/en/1.0.0/], where > tickets are grouped in following types: Added, Changed, Deprecated, Removed, > Fixed, and Security > # {{changelogs/index.md}} will keep an index of all > {{changelogs/<yyyyMMdd>-<version>.md}} files > # The changelog of the *unreleased* version will be kept in > {{changelogs/unreleased}} directory > ## {{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. > ## {{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. > ## {{changelogs/index.md}} and {{changelogs/<yyyyMMdd>-<version>.md}} files > will be symlinked under {{src/site/markdown/changelogs}} directory > # {{bin/generate-changelogs.sh}} script will perform the following tasks: > ## generating a {{changelogs/<yyyyMMdd>-<version>.md}} from the contents of > {{changelogs/unreleased}} > ## removing all {{changelogs/unreleased/<type>_<description>.md}} files > ## generating {{changelogs/index.md}} again > h3. How does a {{changelogs/unreleased/template.md}} file look like? > {code:java} > 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"/> > {code} > h3. What shall I do when I am about to commit a change? > Add a {{changelogs/unreleased/<type>_<description>.md}} file along with your > changes. > h3. 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{}}}. > h3. 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}}. -- This message was sent by Atlassian Jira (v8.20.10#820010)