[
https://issues.apache.org/jira/browse/LOG4J2-3628?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Volkan Yazici updated LOG4J2-3628:
----------------------------------
Description:
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}}.
was:
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{}}}.
> 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)
