[
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: [email protected]):
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)
