LOG4J2-3628 Add changelog templates

CHANGELOG.adoc

@@ -29,10 +29,11 @@ See {log4j-changelog-ref} project for further details; how to use this changelog
 
 == 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:
+Just before a release, three 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>`
+. *changelog entry files needs to be moved* from the _upcoming_ release changelog directory `src/changelog/.<releaseVersionMajor>.x.x`  to the _new_ release changelog directory `src/changelog/<releaseVersion>`
+. *`.changelog.adoc.ftl` needs to be copied* from the _upcoming_ release changelog directory to the _new_ release changelog directory, unless it already exists in the target
+. *`.release.xml` needs to be created* in the _new_ release changelog directory
 
 Due to the nature of release candidates, above steps might need to be repeated multiple times.
 
@@ -45,21 +46,32 @@ Once a release candidate voting reaches to a consensus for release, associated a
 Hence, there are no differences between releases and release candidates.
 ====
 
-How to carry out aforementioned two changes are explained below in steps:
+How to carry out aforementioned 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.
+`changelog-releaser` Maven profile obtains the new release version from `Log4jReleaseVersion` property.
+If needed, you can override it to point to another release version:
+
+[source,bash]
+----
+./mvnw -N -P changelog-releaser -DLog4jReleaseVersion=6.6.6
+----
+====
+. Verify that all changelog entry files are moved from `src/changelog/.<releaseVersionMajor>.x.x` directory (e.g., `src/changelog/.2.x.x`)
+. Verify that `src/changelog/<releaseVersion>` directory (e.g., `src/changelog/2.19.0`) is created, and it contains `.changelog.adoc.ftl`, `.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`; `.changelog.adoc.ftl` will not be touched, if it already 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
+. Edit the populated `.changelog.adoc.ftl`
+. `git add` the changes in `src/changelog` and commit them

pom.xml

@@ -1523,7 +1523,7 @@
         <artifactId>exec-maven-plugin</artifactId>
         <executions>
           <execution>
-            <id>changelog-asciidoc-export</id>
+            <id>changelog-export</id>
             <phase>pre-site</phase>
             <goals>
               <goal>java</goal>
@@ -1537,7 +1537,7 @@
             <groupId>org.apache.logging.log4j.tools</groupId>
             <artifactId>log4j-changelog</artifactId>
           </executableDependency>
-          <mainClass>org.apache.logging.log4j.tools.changelog.exporter.AsciiDocExporter</mainClass>
+          <mainClass>org.apache.logging.log4j.tools.changelog.exporter.ChangelogExporter</mainClass>
           <systemProperties>
             <systemProperty>
               <key>log4j.changelog.directory</key>

src/changelog/.2.x.x/.changelog.adoc.ftl

@@ -0,0 +1,22 @@
+////
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+////
+
+= ${release.version}<#if release.date?has_content> (${release.date})</#if>
+
+Changes staged for the next version that is yet to be released.
+
+<#include "../.changelog-entries.adoc.ftl">

src/changelog/.changelog-entries.adoc.ftl

@@ -0,0 +1,32 @@
+<#if entriesByType?size gt 0>== Changes
+<#list entriesByType as entryType, entries>
+
+== ${entryType?capitalize}
+
+<#list entries as entry>
+* ${entry.description.text?replace("\\s+", " ", "r")} (for <@compress single_line=true>
+<#list entry.issues as issue>${issue.link}[${issue.id}]<#if issue?has_next>, </#if></#list> by
+<#list entry.authors as author>
+<@compress single_line=true>
+<#if !author.id?has_content>${author.name}
+<#elseif author.id == "rgoers">Ralph Goers
+<#elseif author.id == "ggregory">Gary Gregory
+<#elseif author.id == "sdeboy">Scott Deboy
+<#elseif author.id == "rpopma">Remko Popma
+<#elseif author.id == "nickwilliams">Nick Williams
+<#elseif author.id == "mattsicker">Matt Sicker
+<#elseif author.id == "bbrouwer">Bruce Brouwer
+<#elseif author.id == "rgupta">Raman Gupta
+<#elseif author.id == "mikes">Mikael Ståldal
+<#elseif author.id == "ckozak">Carter Kozak
+<#elseif author.id == "vy">Volkan Yazıcı
+<#elseif author.id == "rgrabowski">Ron Grabowski
+<#elseif author.id == "pkarwasz">Piotr P. Karwasz
+<#else>`${author.id}`
+</#if>
+</@compress><#if author?has_next>, </#if>
+</#list>
+</@compress>)
+</#list>
+</#list>
+</#if>

src/changelog/.index.adoc.ftl

@@ -0,0 +1,22 @@
+////
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+////
+
+= Release changelogs
+
+<#list releases as release>
+* xref:${release.changelogFileName}[${release.version}]<#if release.date?has_content> (${release.date})</#if>
+</#list>

src/changelog/2.0-alpha1/.changelog.adoc.ftl

@@ -0,0 +1,20 @@
+////
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+////
+
+= ${release.version}<#if release.date?has_content> (${release.date})</#if>
+
+<#include "../.changelog-entries.adoc.ftl">

src/changelog/2.0-alpha2/.changelog.adoc.ftl

@@ -0,0 +1,20 @@
+////
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+////
+
+= ${release.version}<#if release.date?has_content> (${release.date})</#if>
+
+<#include "../.changelog-entries.adoc.ftl">

src/changelog/2.0-beta1/.changelog.adoc.ftl

@@ -0,0 +1,20 @@
+////
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+////
+
+= ${release.version}<#if release.date?has_content> (${release.date})</#if>
+
+<#include "../.changelog-entries.adoc.ftl">

src/changelog/2.0-beta2/.changelog.adoc.ftl

@@ -0,0 +1,20 @@
+////
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+////
+
+= ${release.version}<#if release.date?has_content> (${release.date})</#if>
+
+<#include "../.changelog-entries.adoc.ftl">

src/changelog/2.0-beta3/.changelog.adoc.ftl

@@ -0,0 +1,20 @@
+////
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+////
+
+= ${release.version}<#if release.date?has_content> (${release.date})</#if>
+
+<#include "../.changelog-entries.adoc.ftl">

src/changelog/2.0-beta4/.changelog.adoc.ftl

@@ -0,0 +1,20 @@
+////
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+////
+
+= ${release.version}<#if release.date?has_content> (${release.date})</#if>
+
+<#include "../.changelog-entries.adoc.ftl">

src/changelog/2.0-beta5/.changelog.adoc.ftl

@@ -0,0 +1,20 @@
+////
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+////
+
+= ${release.version}<#if release.date?has_content> (${release.date})</#if>
+
+<#include "../.changelog-entries.adoc.ftl">

src/changelog/2.0-beta6/.changelog.adoc.ftl

@@ -0,0 +1,20 @@
+////
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+////
+
+= ${release.version}<#if release.date?has_content> (${release.date})</#if>
+
+<#include "../.changelog-entries.adoc.ftl">

src/changelog/2.0-beta7/.changelog.adoc.ftl

@@ -0,0 +1,20 @@
+////
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+////
+
+= ${release.version}<#if release.date?has_content> (${release.date})</#if>
+
+<#include "../.changelog-entries.adoc.ftl">

src/changelog/2.0-beta8/.changelog.adoc.ftl

@@ -0,0 +1,20 @@
+////
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+////
+
+= ${release.version}<#if release.date?has_content> (${release.date})</#if>
+
+<#include "../.changelog-entries.adoc.ftl">

src/changelog/2.0-beta9/.changelog.adoc.ftl

@@ -0,0 +1,20 @@
+////
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+         https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+////
+
+= ${release.version}<#if release.date?has_content> (${release.date})</#if>
+
+<#include "../.changelog-entries.adoc.ftl">