[logging-log4j2] 29/33: LOG4J2-3628 Update `CHANGELOG.adoc`.

[vy...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

vy pushed a commit to branch mvn-site-simplified
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git

commit 6710a394f7c542796ebe7c2e4d649b62f26c13ae
Author: Volkan Yazıcı <vo...@yazi.ci>
AuthorDate: Sun Dec 11 22:12:18 2022 +0100

    LOG4J2-3628 Update `CHANGELOG.adoc`.
---
 CHANGELOG.adoc | 41 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
index e26958ceba..6d3361be54 100644
--- a/CHANGELOG.adoc
+++ b/CHANGELOG.adoc
@@ -17,10 +17,49 @@
 
 :log4j-changelog-ref: https://github.com/apache/logging-log4j-tools/tree/master/log4j-changelog[log4j-changelog]
 
-Changelog sources are stored in xref:src/changelog[`src/changelog`] directory.
+== Where are changelogs stored?
+
+Changelogs are stored in xref:src/changelog[`src/changelog`] directory.
 
 {log4j-changelog-ref} is used to generate AsciiDoc-formatted changelog files during Maven `pre-site` phase and export them to xref:target/generated-sources/site/asciidoc/changelog[`target/generated-sources/site/asciidoc/changelog`] directory.
 These exported AsciiDoc files are not committed, since they are only relevant for the website, and they cause merge-conflicts between feature branches.
 `./mvnw -N site` command can be used to manually generate these files.
 
 See {log4j-changelog-ref} project for further details; how to use this changelog system, what steps are needed while making a new release, etc.
+
+== I am about to deploy a new release. What shall I do?
+
+Just before a release, two things need to happen in the changelog sources:
+
+. Changelog entries of the upcoming release directory `src/changelog/.<releaseVersionMajor>.x.x` needs to be moved to the release changelog directory `src/changelog/<releaseVersion>`
+. `.index.adoc` and `.release.xml` need to be created in the release changelog directory `src/changelog/<releaseVersion>`
+
+Due to the nature of release candidates, above steps might need to be repeated multiple times.
+
+[TIP]
+====
+Log4j _releases_ and _release candidates_ all get deployed to the same https://repository.apache.org/#stagingRepositories[_staging repository_].
+Their `pom.xml` files all contain the same release version, e.g., `2.19.0`.
+There are no `-rc1`, `-rc2`, etc. suffixes in the version of a release candidate.
+Once a release candidate voting reaches to a consensus for release, associated artifacts simply get promoted from the _staging_ to the _public_ repository.
+Hence, there are no differences between releases and release candidates.
+====
+
+How to carry out aforementioned two changes are explained below in steps:
+
+. Populate the `src/changelog/<releaseVersion>` directory (e.g., `src/changelog/2.19.0`) from the upcoming release changelog directory (e.g., `src/changelog/.2.x.x`):
++
+[source,bash]
+----
+./mvnw -N -P changelog-releaser
+----
+. Verify that `src/changelog/.<releaseVersionMajor>.x.x` directory (e.g., `src/changelog/.2.x.x`) is emptied
+. Verify that `src/changelog/<releaseVersion>` directory (e.g., `src/changelog/2.19.0`) is created, and it contains `.intro.adoc`, `.release.xml`, and changelog entry files
++
+[IMPORTANT]
+====
+If `src/changelog/<releaseVersion>` directory (e.g., `src/changelog/2.19.0`) already exists with certain content, `changelog-releaser` profile will only move new changelog entry files and override `.release.xml`; `.intro.adoc` will not be touched, if exists.
+This allows one to run `changelog-releaser` profile multiple times, e.g., to incorporate changes added to a release candidate.
+====
+. Edit the created `.intro.adoc`
+. `git add` the changes in `/src/changelog` and commit them