[jira] [Comment Edited] (LOG4J2-3628) Migrate from maven-changes-plugin to a merge-conflict-free Markdown-based solution

["Ralph Goers (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/LOG4J2-3628?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17631243#comment-17631243 ] 

Ralph Goers edited comment on LOG4J2-3628 at 11/9/22 10:50 PM:
---------------------------------------------------------------

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. At the very least the format should be json to identify a) the contributor of the fix, if there is one b) the committer that merged the fix. c) the issue number it addresses d) description of the problem or enhancement and/or what the change does.

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, 3) it does avoid merge conflicts. 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.

I should note that we could create a Maven plugin that takes individual change files as described above and creates a maven.xml file before invoking the maven-changes-plugin, which would also avoid merge conflicts. That said, I've never considered merge conflicts to be that big of a deal on changes.xml.


was (Author: ralph.goers@dslextreme.com):
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)