This is an automated email from the ASF dual-hosted git repository. vy pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/logging-parent.git
commit 6050b5c490e3987545178799d57d801355170695 Author: Volkan Yazıcı <[email protected]> AuthorDate: Wed Sep 20 13:10:03 2023 +0200 Add an AsciiDoc-based website and its CI+`pom.xml` foundation --- .github/workflows/build.yaml | 5 +- .github/workflows/deploy-release-reusable.yaml | 61 +++++++++--- .mvn/jvm.config | 2 + README.adoc | 41 +------- RELEASE-NOTES.adoc | 21 ----- antora-playbook.yaml | 29 ------ pom.xml | 103 +++++++-------------- src/antora/antora.tmpl.yml | 44 --------- src/antora/antora.yml | 44 --------- src/changelog/.10.x.x/.release-notes.adoc.ftl | 20 ++-- ...antora-profile.xml => add-asciidoc-profile.xml} | 2 +- .../{add-antora-profile.xml => add-website.xml} | 2 +- src/changelog/.10.x.x/remove-outputTimestamp.xml | 2 +- src/changelog/.changelog.adoc.ftl | 2 +- src/changelog/.index.adoc.ftl | 12 ++- src/changelog/10.0.0/.release-notes.adoc.ftl | 14 ++- .../index.adoc => site/_constants.adoc} | 22 +++-- .../index.adoc => site/_constants.tmpl.adoc} | 21 +++-- .../ROOT/pages/index.adoc => site/features.adoc} | 33 ++----- README.adoc => src/site/index.adoc | 77 ++++++++++----- .../site/release-instructions.adoc | 60 ++++++------ .../index.adoc => site/release-notes.adoc} | 14 ++- .../release-notes/_10.0.0.adoc} | 18 +++- .../release-notes/_10.x.x.adoc} | 32 ++++--- .../modules/ROOT/nav.adoc => site/usage.adoc} | 21 ++++- 25 files changed, 305 insertions(+), 397 deletions(-) diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index a6571aa..aa7a06a 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -48,16 +48,19 @@ jobs: needs: build if: github.repository == 'apache/logging-parent' && github.ref == 'refs/heads/main' uses: apache/logging-parent/.github/workflows/deploy-snapshot-reusable.yaml@main + # Secrets for deployments secrets: inherit deploy-release: needs: build if: github.repository == 'apache/logging-parent' && startsWith(github.ref, 'refs/heads/release/') uses: apache/logging-parent/.github/workflows/deploy-release-reusable.yaml@main + # Secrets for deployments secrets: inherit # Write permissions to allow the Maven `revision` property update, changelog release, etc. permissions: contents: write with: - project-name: logging-parent + project-id: logging-parent distribution-attachment-count: 0 + site-enabled: true diff --git a/.github/workflows/deploy-release-reusable.yaml b/.github/workflows/deploy-release-reusable.yaml index 9320808..f74a445 100644 --- a/.github/workflows/deploy-release-reusable.yaml +++ b/.github/workflows/deploy-release-reusable.yaml @@ -24,11 +24,14 @@ on: description: "The Java *compiler* version. (Target is fixed: 8)" default: 17 type: string - project-name: + project-id: description: Identifier used in the distribution artifact and Subversion repository folder filenames (e.g., `logging-parent`) required: true type: string - # `distribution-*` input defaults should match the ones in `pom.xml`! + site-enabled: + description: Flag indicating if a website should be generated prior to deployment using `./mvnw -N site` + default: false + type: boolean distribution-attachment-filepath-pattern: description: The regex pattern matched against the full filepath for determining attachments to be included in the distribution default: |- @@ -117,14 +120,41 @@ jobs: ./mvnw \ --non-recursive --batch-mode --errors --no-transfer-progress \ -P changelog-release - git add src/changelog src/antora + git add src/changelog if [ -n "$(git status --porcelain)" ]; then git config user.name "ASF Logging Services RM" git config user.email [email protected] - git commit -S src/changelog src/antora -m "Release changelog for version \`$PROJECT_VERSION\`" + git commit -S src/changelog -m "Release changelog for version \`$PROJECT_VERSION\`" git push origin fi + - name: Commit generated sources + shell: bash + run: | + ./mvnw \ + --non-recursive --batch-mode --errors --no-transfer-progress \ + generate-sources + git add src/site + if [ -n "$(git status --porcelain)" ]; then + git config user.name "ASF Logging Services RM" + git config user.email [email protected] + git commit -S src/site -m "Add auto-generated sources" + git push origin + fi + + - name: Build the website + if: inputs.site-enabled + shell: bash + run: | + gpg --list-secret-keys + ./mvnw \ + --show-version --batch-mode --errors --no-transfer-progress \ + --non-recursive \ + site + cd target/site + find . -print0 | xargs -0 touch -d 1970-01-01T00:00:00Z + find . -print0 | sort --zero-terminated | xargs -0 zip -roX ../site.zip + - name: Upload to Nexus shell: bash run: | @@ -146,12 +176,13 @@ jobs: # Generate the distribution (i.e., `src.zip` and optional `bin.zip`) ./mvnw \ --show-version --batch-mode --errors --no-transfer-progress \ - --non-recursive -P distribution \ + --non-recursive \ + -P distribution \ -DattachmentFilepathPattern=${{ inputs.distribution-attachment-filepath-pattern }} \ -DattachmentCount=${{ inputs.distribution-attachment-count }} # Rename distribution files - export DIST_FILENAME_PREFIX="apache-${{ inputs.project-name }}" + export DIST_FILENAME_PREFIX="apache-${{ inputs.project-id }}" export DIST_FILENAME_VERSIONED_PREFIX="${DIST_FILENAME_PREFIX}-${PROJECT_VERSION}" export DIST_FILEPATH_PREFIX="/tmp/${DIST_FILENAME_VERSIONED_PREFIX}" export DIST_FILEPATH_SRC="${DIST_FILEPATH_PREFIX}-src.zip" @@ -190,14 +221,14 @@ jobs: "https://dist.apache.org/repos/dist/dev/logging"; \ "$SVN_DIR" cd "$SVN_DIR" - svn up --depth files "$PROJECT_NAME" + svn up --depth files "$PROJECT_ID" # Switch to the project folder - if [ \! -d "$PROJECT_NAME" ]; then - mkdir -p "$PROJECT_NAME" - svn add "$PROJECT_NAME" + if [ \! -d "$PROJECT_ID" ]; then + mkdir -p "$PROJECT_ID" + svn add "$PROJECT_ID" fi - cd "$PROJECT_NAME" + cd "$PROJECT_ID" # Clean up old files find . -name "${DIST_FILENAME_PREFIX}*" -type f -print0 | xargs -0 -r svn delete @@ -208,6 +239,11 @@ jobs: > "${DIST_FILENAME_VERSIONED_PREFIX}-email-${EMAIL_TYPE}.txt" done + # Copy the site + if [ "$SITE_ENABLED" == "true" ]; then + cp "$GITHUB_WORKSPACE/target/site.zip" > "${DIST_FILENAME_VERSIONED_PREFIX}-site.zip" + fi + # Copy the distribution cp "$DIST_FILEPATH_PREFIX"* . @@ -219,6 +255,7 @@ jobs: -m "Added \`${DIST_FILENAME_PREFIX}\` artifacts for release \`${PROJECT_VERSION}\`" env: - PROJECT_NAME: ${{ inputs.project-name }} + PROJECT_ID: ${{ inputs.project-id }} SVN_USERNAME: ${{ secrets.SVN_USERNAME }} SVN_PASSWORD: ${{ secrets.SVN_PASSWORD }} + SITE_ENABLED: ${{ inputs.site-enabled }} diff --git a/.mvn/jvm.config b/.mvn/jvm.config index 6f7d1c8..b0983d8 100644 --- a/.mvn/jvm.config +++ b/.mvn/jvm.config @@ -9,3 +9,5 @@ --add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED --add-opens jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED --add-opens jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED +--add-opens java.base/sun.nio.ch=ALL-UNNAMED +--add-opens java.base/java.io=ALL-UNNAMED \ No newline at end of file diff --git a/README.adoc b/README.adoc index 5307275..5078251 100644 --- a/README.adoc +++ b/README.adoc @@ -19,43 +19,4 @@ https://github.com/apache/logging-parent/actions[image:https://github.com/apache https://search.maven.org/search?q=g:org.apache.logging%20a:logging-parent[image:https://img.shields.io/maven-central/v/org.apache.logging/logging-parent.svg[Maven Central]] https://www.apache.org/licenses/LICENSE-2.0.txt[image:https://img.shields.io/github/license/apache/logging-parent.svg[License]] -Parent project **internally** used in Maven-based projects of https://logging.apache.org[the Apache Logging Services projects]. - -== Build - -This project requires Java 17 for compilation. -You can build using `./mvnw verify` command. - -== Usage - -See https://logging.apache.org/logging-parent[the website]. - -== Distribution - -In accordance with the Apache Software Foundation's release https://infra.apache.org/release-distribution.html[distribution policy] and https://infra.apache.org/release-publishing.html[creation process], project artifacts are _officially_ accessible from the following locations: - -* ASF https://repository.apache.org/content/repositories/releases[Release] and https://repository.apache.org/content/repositories/snapshots[snapshot] repositories (mirrored to https://central.sonatype.dev/[the Maven Central Repository]) -* ASF https://downloads.apache.org/logging/logging-parent[Distribution directory] - -See xref:RELEASING.adoc[release instructions] for further details. - -== Support - -Please keep in mind that this project is intended for internal usage only. -You can use GitHub Issues for feature requests and bug reports – not questions! -See https://logging.apache.org/log4j/2.x/support.html[the Log4j support policy] for details. - -== Security - -If you have encountered an unlisted security vulnerability or other unexpected behaviour that has security impact, please report them privately to mailto:[email protected][the Log4j security mailing list]. -See https://logging.apache.org/log4j/2.x/security.html[the Log4j Security page] for further details. - -== License - -Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. -See xref:NOTICE.txt[] 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. +Parent project **internally** used in Maven-based projects of https://logging.apache.org[the Apache Logging Services] projects. See https://logging.apache.org/logging-parent[the project website] for further information. diff --git a/RELEASE-NOTES.adoc b/RELEASE-NOTES.adoc deleted file mode 100644 index 439caf0..0000000 --- a/RELEASE-NOTES.adoc +++ /dev/null @@ -1,21 +0,0 @@ -//// -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. -//// - -This project uses https://github.com/apache/logging-log4j-tools/tree/main/log4j-changelog-maven-plugin[`log4j-changelog-maven-plugin`] for keeping a changelog and generating release notes. - -Changelog files are located under xref:src/changelog[`src/changelog`]. -Release notes are automatically exported during Maven `generate-sources` phase to xref:src/antora/modules/ROOT/release-notes[`src/antora/modules/ROOT/release-notes`]. diff --git a/antora-playbook.yaml b/antora-playbook.yaml deleted file mode 100644 index b714066..0000000 --- a/antora-playbook.yaml +++ /dev/null @@ -1,29 +0,0 @@ -# -# 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 -# -# http://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. -# -site: - title: Logging Parent - url: "https://logging.apache.org/logging-parent"; - start_page: "logging-parent::index.adoc" -content: - sources: - - url: ./ - branches: HEAD - start_path: src/antora -ui: - bundle: - url: "https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable"; - snapshot: true diff --git a/pom.xml b/pom.xml index e5f33b6..3b327f5 100644 --- a/pom.xml +++ b/pom.xml @@ -538,7 +538,7 @@ <build> <plugins> - <!-- export release notes to `src/antora/modules/ROOT/pages/release-notes` --> + <!-- export release notes to `src/site` --> <plugin> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-changelog-maven-plugin</artifactId> @@ -550,16 +550,17 @@ </goals> <phase>generate-sources</phase> <configuration> - <outputDirectory>src/antora/modules/ROOT/pages/release-notes</outputDirectory> + <outputDirectory>src/site</outputDirectory> <indexTemplates> <template> <source>.index.adoc.ftl</source> + <target>release-notes.adoc</target> </template> </indexTemplates> <changelogTemplates> <template> <source>.release-notes.adoc.ftl</source> - <target>%v.adoc</target> + <target>release-notes/_%v.adoc</target> </template> </changelogTemplates> </configuration> @@ -688,7 +689,7 @@ // Find auxiliary files that will go into the binary distribution SortedMap pathByFile = new TreeMap(); - pathByFile.put("RELEASE-NOTES.adoc", new File("src/antora/modules/ROOT/pages/release-notes/${project.version}.adoc").toPath()); + pathByFile.put("RELEASE-NOTES.adoc", new File("src/site/release-notes/${project.version}.adoc").toPath()); pathByFile.put("README.adoc", new File("README.adoc").toPath()); pathByFile.put("NOTICE.txt", new File("NOTICE.txt").toPath()); pathByFile.put("LICENSE.txt", new File("LICENSE.txt").toPath()); @@ -845,35 +846,35 @@ </profile> - <!-- `antora-tmpl-yml` profile to generate `src/antora/antora.yml` from `src/antora/antora.tmpl.yml` --> + <!-- `constants-tmpl-adoc` profile to generate `src/site/_constants.adoc` from `src/site/_constants.tmpl.adoc` --> <profile> - <id>antora-tmpl-yml</id> + <id>constants-tmpl-adoc</id> <activation> <file> - <exists>src/antora/antora.tmpl.yml</exists> + <exists>src/site/_constants.tmpl.adoc</exists> </file> </activation> <build> <plugins> - <!-- copy `src/antora/antora.tmpl.yml` to `target/antora-yml/antora.yml` --> + <!-- copy `src/site/_constants.tmpl.adoc` to `target/constants-adoc/_constants.adoc` --> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-antrun-plugin</artifactId> <executions> <execution> - <id>copy-antora-yml</id> + <id>copy-constants-adoc</id> <goals> <goal>run</goal> </goals> <phase>generate-sources</phase> <configuration> <target> - <copy overwrite="true" tofile="${project.build.directory}/antora-yml/antora.yml" verbose="true"> - <fileset file="src/antora/antora.tmpl.yml" /> + <copy overwrite="true" tofile="${project.build.directory}/constants-adoc/_constants.adoc" verbose="true"> + <fileset file="src/site/_constants.tmpl.adoc" /> </copy> </target> </configuration> @@ -881,22 +882,22 @@ </executions> </plugin> - <!-- process `target/antora-yml` and output to `src/antora` --> + <!-- process `target/constants-adoc` and output to `src/site` --> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-resources-plugin</artifactId> <executions> <execution> - <id>filter-antora-yml</id> + <id>filter-constants-adoc</id> <goals> <goal>copy-resources</goal> </goals> <phase>process-sources</phase> <configuration> - <outputDirectory>src/antora</outputDirectory> + <outputDirectory>src/site</outputDirectory> <resources> <resource> - <directory>${project.build.directory}/antora-yml</directory> + <directory>${project.build.directory}/constants-adoc</directory> <filtering>true</filtering> </resource> </resources> @@ -910,83 +911,51 @@ </profile> - <!-- `antora` profile to generate `target/site` from `src/antora` --> + <!-- `asciidoc` profile to generate `target/site` from `src/site` --> <profile> - <id>antora</id> + <id>asciidoc</id> <activation> <file> - <exists>src/antora</exists> + <exists>src/site</exists> </file> </activation> <properties> - <!-- dependency versions --> - <antora.version>3.1.4</antora.version> - <http-server.version>14.1.1</http-server.version> - <node.version>v18.12.0</node.version> - <npm.version>9.8.1</npm.version> + <!-- disable `maven-site-plugin`--> + <maven.site.skip>true</maven.site.skip> + <maven.site.deploy.skip>true</maven.site.deploy.skip> <!-- plugin versions --> - <exec-maven-plugin.version>3.1.0</exec-maven-plugin.version> - <frontend-maven-plugin.version>1.14.0</frontend-maven-plugin.version> + <asciidoctor-maven-plugin.version>2.2.4</asciidoctor-maven-plugin.version> </properties> <build> <plugins> - <!-- Install `node`, `npm`, `antora`, etc. --> <plugin> - <groupId>com.github.eirslett</groupId> - <artifactId>frontend-maven-plugin</artifactId> - <version>${frontend-maven-plugin.version}</version> + <groupId>org.asciidoctor</groupId> + <artifactId>asciidoctor-maven-plugin</artifactId> + <version>${asciidoctor-maven-plugin.version}</version> <executions> <execution> - <id>install-node-and-npm</id> + <id>export-asciidoc-to-html</id> <goals> - <goal>install-node-and-npm</goal> - </goals> - <phase>pre-site</phase> - <configuration> - <nodeVersion>${node.version}</nodeVersion> - <npmVersion>${npm.version}</npmVersion> - </configuration> - </execution> - <execution> - <id>npm-install-antora</id> - <goals> - <goal>npm</goal> - </goals> - <phase>pre-site</phase> - <configuration> - <arguments>install @antora/cli@${antora.version} @antora/site-generator-default@${antora.version}</arguments> - </configuration> - </execution> - </executions> - </plugin> - - <!-- Run `antora` --> - <plugin> - <groupId>org.codehaus.mojo</groupId> - <artifactId>exec-maven-plugin</artifactId> - <version>${exec-maven-plugin.version}</version> - <executions> - <execution> - <id>run-antora</id> - <goals> - <goal>exec</goal> + <goal>process-asciidoc</goal> </goals> <phase>site</phase> <configuration> - <executable>node/node</executable> - <arguments> - <argument>node_modules/.bin/antora</argument> - <argument>antora-playbook.yaml</argument> - <argument>--to-dir=${project.build.directory}/site</argument> - </arguments> + <sourceDirectory>src/site</sourceDirectory> + <outputDirectory>${project.build.directory}/site</outputDirectory> + <preserveDirectories>true</preserveDirectories> + <attributes> + <source-highlighter>coderay</source-highlighter> + <toc>left</toc> + <icons>font</icons> + </attributes> </configuration> </execution> </executions> diff --git a/src/antora/antora.tmpl.yml b/src/antora/antora.tmpl.yml deleted file mode 100644 index 30a6833..0000000 --- a/src/antora/antora.tmpl.yml +++ /dev/null @@ -1,44 +0,0 @@ -# -# 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 -# -# http://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. -# - -# ██ ██ █████ ██████ ███ ██ ██ ███ ██ ██████ ██ -# ██ ██ ██ ██ ██ ██ ████ ██ ██ ████ ██ ██ ██ -# ██ █ ██ ███████ ██████ ██ ██ ██ ██ ██ ██ ██ ██ ███ ██ -# ██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ -# ███ ███ ██ ██ ██ ██ ██ ████ ██ ██ ████ ██████ ██ -# -# IF THIS FILE IS CALLED `antora.yaml`, DO NOT EDIT IT! -# ALWAYS EDIT `antora.tmpl.adoc`! -# -# `antora.yaml` is generated from `antora.tmpl.yaml` by Maven. -# Hence, you must always -# -# 1. Edit `antora.tmpl.yaml` -# 2. Run `./mvnw generate-resources` -# 3. Commit both `antora.tmpl.yaml` and `antora.yaml` - -name: logging-parent -title: Logging Parent -version: 10.x -start_page: index.adoc -asciidoc: - attributes: - project-scm-url: "${scm.url}" - project-version: "${project.version}" - project-name: "${project.name}" -nav: - - modules/ROOT/nav.adoc diff --git a/src/antora/antora.yml b/src/antora/antora.yml deleted file mode 100644 index e6a7e0e..0000000 --- a/src/antora/antora.yml +++ /dev/null @@ -1,44 +0,0 @@ -# -# 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 -# -# http://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. -# - -# ██ ██ █████ ██████ ███ ██ ██ ███ ██ ██████ ██ -# ██ ██ ██ ██ ██ ██ ████ ██ ██ ████ ██ ██ ██ -# ██ █ ██ ███████ ██████ ██ ██ ██ ██ ██ ██ ██ ██ ███ ██ -# ██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ -# ███ ███ ██ ██ ██ ██ ██ ████ ██ ██ ████ ██████ ██ -# -# IF THIS FILE IS CALLED `antora.yaml`, DO NOT EDIT IT! -# ALWAYS EDIT `antora.tmpl.adoc`! -# -# `antora.yaml` is generated from `antora.tmpl.yaml` by Maven. -# Hence, you must always -# -# 1. Edit `antora.tmpl.yaml` -# 2. Run `./mvnw generate-resources` -# 3. Commit both `antora.tmpl.yaml` and `antora.yaml` - -name: logging-parent -title: Logging Parent -version: 10.x -start_page: index.adoc -asciidoc: - attributes: - project-scm-url: "https://github.com/apache/logging-parent"; - project-version: "10.1.0-SNAPSHOT" - project-name: "Apache Logging Parent" -nav: - - modules/ROOT/nav.adoc diff --git a/src/changelog/.10.x.x/.release-notes.adoc.ftl b/src/changelog/.10.x.x/.release-notes.adoc.ftl index 5cded5b..13f345a 100644 --- a/src/changelog/.10.x.x/.release-notes.adoc.ftl +++ b/src/changelog/.10.x.x/.release-notes.adoc.ftl @@ -22,19 +22,23 @@ ██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ███ ██ ██ ██ ██ ██ ████ ██ ██ ████ ██████ ██ - IF THIS FILE DOESN'T HAVE A `.ftl` SUFFIX, IT IS AUTO-GENERATED, DO NOT EDIT! + IF THIS FILE DOESN'T HAVE A `.ftl` SUFFIX, IT IS AUTO-GENERATED, DO NOT EDIT IT! - Version-specific release notes (`7.8.0.adoc`, etc.) are generated from `src/changelog/.changelog.adoc.ftl`. + Version-specific release notes (`7.8.0.adoc`, etc.) are generated from `src/changelog/*/.release-notes.adoc.ftl`. Auto-generation happens during `generate-sources` phase of Maven. + Hence, you must always + + 1. Find and edit the associated `.release-notes.adoc.ftl` + 2. Run `./mvnw generate-sources` + 3. Commit both `.release-notes.adoc.ftl` and the generated `7.8.0.adoc` //// -== ${release.version}<#if release.date?has_content> (${release.date})</#if> +[#release-notes-${release.version?replace("[^a-zA-Z0-9]", "-", "r")}] +=== ${release.version}<#if release.date?has_content> -This minor release contains various improvements that we expect to relieve the load on `pom.xml` and GitHub Actions workflows of Maven-based projects we parent. -This is of particular importance while managing and cutting releases from multiple repositories. -See `README.adoc` for the complete list of features and their usage. +Date:: ${release.date}</#if> -See [this `logging-log4j-tools` GitHub Actions workflow run](https://github.com/apache/logging-log4j-tools/actions/runs/6120297528) demonstrating a successful release cut using a SNAPSHOT version of this `logging-parent` release. -All preparations (release notes, distribution ZIP, vote & announcement emails, etc.) are staged to both Nexus and SVN and waiting the release manager to proceed. +This minor release focuses on shipping AsciiDoc-based website generation convenience targeting the `src/site` folder. +As a part of this effort, `logging-parent` started publishing https://logging.apache.org/logging-parent[its own website] and `log4j-changelog` support is switched from Markdown to AsciiDoc. <#include "../.changelog.adoc.ftl"> diff --git a/src/changelog/.10.x.x/add-antora-profile.xml b/src/changelog/.10.x.x/add-asciidoc-profile.xml similarity index 69% copy from src/changelog/.10.x.x/add-antora-profile.xml copy to src/changelog/.10.x.x/add-asciidoc-profile.xml index aa2c0f5..41adba1 100644 --- a/src/changelog/.10.x.x/add-antora-profile.xml +++ b/src/changelog/.10.x.x/add-asciidoc-profile.xml @@ -4,5 +4,5 @@ xsi:schemaLocation="http://logging.apache.org/log4j/changelog https://logging.apache.org/log4j/changelog-0.1.1.xsd"; type="added"> <author id="github:vy"/> - <description format="asciidoc">Added `antora` and `antora-tmpl-yml` profiles to generate Antora-based websites from `src/antora`</description> + <description format="asciidoc">Added `asciidoc` and `constants-tmpl-adoc` profiles to generate AsciiDoc-based websites from `src/site`</description> </entry> diff --git a/src/changelog/.10.x.x/add-antora-profile.xml b/src/changelog/.10.x.x/add-website.xml similarity index 69% rename from src/changelog/.10.x.x/add-antora-profile.xml rename to src/changelog/.10.x.x/add-website.xml index aa2c0f5..5049731 100644 --- a/src/changelog/.10.x.x/add-antora-profile.xml +++ b/src/changelog/.10.x.x/add-website.xml @@ -4,5 +4,5 @@ xsi:schemaLocation="http://logging.apache.org/log4j/changelog https://logging.apache.org/log4j/changelog-0.1.1.xsd"; type="added"> <author id="github:vy"/> - <description format="asciidoc">Added `antora` and `antora-tmpl-yml` profiles to generate Antora-based websites from `src/antora`</description> + <description format="asciidoc">Started publishing https://logging.apache.org/logging-parent[the project website]</description> </entry> diff --git a/src/changelog/.10.x.x/remove-outputTimestamp.xml b/src/changelog/.10.x.x/remove-outputTimestamp.xml index eff94d0..28494c0 100644 --- a/src/changelog/.10.x.x/remove-outputTimestamp.xml +++ b/src/changelog/.10.x.x/remove-outputTimestamp.xml @@ -4,5 +4,5 @@ xsi:schemaLocation="http://logging.apache.org/log4j/changelog https://logging.apache.org/log4j/changelog-0.1.1.xsd"; type="removed"> <author id="github:vy"/> - <description format="asciidoc">Removed `project.build.outputTimestamp` override since it is already provided by the parent POM and its old value `0` was causing reproducibility issues for `spring-boot:repackage`</description> + <description format="asciidoc">Removed `project.build.outputTimestamp` override since it is already provided by the parent POM and its old value `0` was causing https://github.com/spring-projects/spring-boot/pull/37438[reproducibility issues] for `spring-boot:repackage`</description> </entry> diff --git a/src/changelog/.changelog.adoc.ftl b/src/changelog/.changelog.adoc.ftl index 5c8e30c..ebd41f0 100644 --- a/src/changelog/.changelog.adoc.ftl +++ b/src/changelog/.changelog.adoc.ftl @@ -17,7 +17,7 @@ <#if entriesByType?size gt 0> <#list entriesByType as entryType, entries> -=== ${entryType?capitalize} +==== ${entryType?capitalize} <#list entries as entry> * ${entry.description.text?replace("\\s+", " ", "r")}<#if entry.issues?has_content> (<#list entry.issues as issue>${issue.link}[${issue.id}]<#if issue?has_next>, </#if></#list>)</#if> diff --git a/src/changelog/.index.adoc.ftl b/src/changelog/.index.adoc.ftl index 97f5d7a..0d60c17 100644 --- a/src/changelog/.index.adoc.ftl +++ b/src/changelog/.index.adoc.ftl @@ -22,14 +22,20 @@ ██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ███ ██ ██ ██ ██ ██ ████ ██ ██ ████ ██████ ██ - IF THIS FILE IS CALLED `index.adoc`, IT IS AUTO-GENERATED, DO NOT EDIT! + IF THIS FILE IS CALLED `index.adoc`, IT IS AUTO-GENERATED, DO NOT EDIT IT! Release notes `index.adoc` is generated from `src/changelog/.index.adoc.ftl`. Auto-generation happens during `generate-sources` phase of Maven. + Hence, you must always + + 1. Edit `.index.adoc.ftl` + 2. Run `./mvnw generate-sources` + 3. Commit both `.index.adoc.ftl` and the generated `.index.adoc` //// -= Release Notes +[#release-notes] +== Release Notes <#list releases as release> -include::${release.version}.adoc[${release.version}] +include::release-notes/_${release.version}.adoc[] </#list> diff --git a/src/changelog/10.0.0/.release-notes.adoc.ftl b/src/changelog/10.0.0/.release-notes.adoc.ftl index 897be4c..506cf5e 100644 --- a/src/changelog/10.0.0/.release-notes.adoc.ftl +++ b/src/changelog/10.0.0/.release-notes.adoc.ftl @@ -22,13 +22,21 @@ ██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ███ ██ ██ ██ ██ ██ ████ ██ ██ ████ ██████ ██ - IF THIS FILE DOESN'T HAVE A `.ftl` SUFFIX, IT IS AUTO-GENERATED, DO NOT EDIT! + IF THIS FILE DOESN'T HAVE A `.ftl` SUFFIX, IT IS AUTO-GENERATED, DO NOT EDIT IT! - Version-specific release notes (`7.8.0.adoc`, etc.) are generated from `src/changelog/.changelog.adoc.ftl`. + Version-specific release notes (`7.8.0.adoc`, etc.) are generated from `src/changelog/*/.release-notes.adoc.ftl`. Auto-generation happens during `generate-sources` phase of Maven. + Hence, you must always + + 1. Find and edit the associated `.release-notes.adoc.ftl` + 2. Run `./mvnw generate-sources` + 3. Commit both `.release-notes.adoc.ftl` and the generated `7.8.0.adoc` //// -== ${release.version}<#if release.date?has_content> (${release.date})</#if> +[#release-notes-${release.version?replace("[^a-zA-Z0-9]", "-", "r")}] +=== ${release.version}<#if release.date?has_content> + +Date:: ${release.date}</#if> This minor release contains various improvements that we expect to relieve the load on `pom.xml` and GitHub Actions workflows of Maven-based projects we parent. This is of particular importance while managing and cutting releases from multiple repositories. diff --git a/src/antora/modules/ROOT/pages/release-notes/index.adoc b/src/site/_constants.adoc similarity index 70% copy from src/antora/modules/ROOT/pages/release-notes/index.adoc copy to src/site/_constants.adoc index d0a460f..ec13003 100644 --- a/src/antora/modules/ROOT/pages/release-notes/index.adoc +++ b/src/site/_constants.adoc @@ -6,7 +6,7 @@ (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - http://www.apache.org/licenses/LICENSE-2.0 + http://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, @@ -22,13 +22,19 @@ ██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ███ ██ ██ ██ ██ ██ ████ ██ ██ ████ ██████ ██ - IF THIS FILE IS CALLED `index.adoc`, IT IS AUTO-GENERATED, DO NOT EDIT! + IF THIS FILE DOESN'T HAVE A `.tmpl.adoc` SUFFIX, IT IS AUTO-GENERATED, DO NOT EDIT! - Release notes `index.adoc` is generated from `src/changelog/.index.adoc.ftl`. - Auto-generation happens during `generate-sources` phase of Maven. -//// + `constants.adoc` is auto-generated from `constants.tmpl.adoc` during `generate-sources` phase of Maven. + Hence you must always, -= Release Notes + 1. Edit `constants.tmpl.adoc` + 2. Run `./mvnw generate-resources` + 3. Commit both `constants.tmpl.adoc` and `constants.adoc` +//// -include::10.x.x.adoc[10.x.x] -include::10.0.0.adoc[10.0.0] +:project-github-url: https://github.com/apache/logging-parent +:project-version: 1.2.3 +:project-name: Logging Parent +:project-id: logging-parent +:java-target-version: 1.8 +:java-compiler-version: [17,18) diff --git a/src/antora/modules/ROOT/pages/release-notes/index.adoc b/src/site/_constants.tmpl.adoc similarity index 71% copy from src/antora/modules/ROOT/pages/release-notes/index.adoc copy to src/site/_constants.tmpl.adoc index d0a460f..937386b 100644 --- a/src/antora/modules/ROOT/pages/release-notes/index.adoc +++ b/src/site/_constants.tmpl.adoc @@ -6,7 +6,7 @@ (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - http://www.apache.org/licenses/LICENSE-2.0 + http://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, @@ -22,13 +22,20 @@ ██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ███ ██ ██ ██ ██ ██ ████ ██ ██ ████ ██████ ██ - IF THIS FILE IS CALLED `index.adoc`, IT IS AUTO-GENERATED, DO NOT EDIT! + IF THIS FILE DOESN'T HAVE A `.tmpl.adoc` SUFFIX, IT IS AUTO-GENERATED, DO NOT EDIT IT! - Release notes `index.adoc` is generated from `src/changelog/.index.adoc.ftl`. + `_constants.adoc` is auto-generated from `_constants.tmpl.adoc`. Auto-generation happens during `generate-sources` phase of Maven. -//// + Hence, you must always -= Release Notes + 1. Edit `_constants.tmpl.adoc` + 2. Run `./mvnw generate-resources` + 3. Commit both `_constants.tmpl.adoc` and the generated `_constants.adoc` +//// -include::10.x.x.adoc[10.x.x] -include::10.0.0.adoc[10.0.0] +:project-github-url: ${scm.url} +:project-version: ${project.version} +:project-name: Logging Parent +:project-id: logging-parent +:java-target-version: ${java.version} +:java-compiler-version: ${minimalJavaBuildVersion} diff --git a/src/antora/modules/ROOT/pages/index.adoc b/src/site/features.adoc similarity index 69% rename from src/antora/modules/ROOT/pages/index.adoc rename to src/site/features.adoc index 0128f77..8294346 100644 --- a/src/antora/modules/ROOT/pages/index.adoc +++ b/src/site/features.adoc @@ -15,17 +15,14 @@ limitations under the License. //// -:log4j-url: https://logging.apache.org/log4j/2.x -:log4j-api-url: {log4j-url}/manual/api-separation.html - -= Logging Parent - -{project-name} is the parent project **internally** used in Maven-based projects of https://logging.apache.org[the Apache Logging Services]. +include::_constants.adoc[] +[#features] == Features -This project aims to deliver the following features. +{project-name} aims to deliver the following features. +[#parent-pom] === Parent POM The provided parent POM features the following conveniences: @@ -34,8 +31,9 @@ The provided parent POM features the following conveniences: * https://github.com/apache/logging-log4j-tools/tree/main/log4j-changelog-maven-plugin[`log4j-changelog-maven-plugin`] integration for changelog and release note management * https://maven.apache.org/enforcer/maven-enforcer-plugin/[`maven-enforcer-plugin`] checks * https://github.com/diffplug/spotless/tree/main/plugin-maven[`spotless-maven-plugin`] integration for code formatting -* https://antora.org/[Antora]-based site generation +* https://asciidoc.org/[AsciiDoc]-based site generation +[#reusable-workflows] === Reusable GitHub Actions workflows The provided reusable GitHub Actions workflows feature the following conveniences: @@ -54,22 +52,3 @@ The provided reusable GitHub Actions workflows feature the following convenience * Generates the distribution ZIP containing Git-tracked sources, release notes, binary attachments, `NOTICE.txt`, etc. * Generates the release vote & announcement emails * Uploads the distribution ZIP and emails to SVN - -== Usage - -You can use this project as follows: - -. Add `org.apache.logging:logging-parent` as a `parent` to your `pom.xml` -.. Check if `./mvnw verify` succeeds, otherwise make necessary changes -. Bootstrap the support files (`.gitignore`, `.github/workflows/build.yaml`, etc.) using -+ -[source,bash] ----- -./mvnw -N -P boostrap \ - -DrepositoryName=... \ # <1> - -DprojectName=... # <2> ----- -<1> The name of the repository (e.g., `logging-log4j-tools`) -<2> The name of the project (e.g., `log4j-tools`) -+ -and adapt them their content as you see fit diff --git a/README.adoc b/src/site/index.adoc similarity index 50% copy from README.adoc copy to src/site/index.adoc index 5307275..4b419a3 100644 --- a/README.adoc +++ b/src/site/index.adoc @@ -1,35 +1,55 @@ //// -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. + 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 + + http://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. //// -https://github.com/apache/logging-parent/actions[image:https://github.com/apache/logging-parent/workflows/build/badge.svg[Actions Status]] -https://search.maven.org/search?q=g:org.apache.logging%20a:logging-parent[image:https://img.shields.io/maven-central/v/org.apache.logging/logging-parent.svg[Maven Central]] -https://www.apache.org/licenses/LICENSE-2.0.txt[image:https://img.shields.io/github/license/apache/logging-parent.svg[License]] +include::_constants.adoc[] +:log4j-url: https://logging.apache.org/log4j/2.x +:log4j-api-url: {log4j-url}/manual/api-separation.html -Parent project **internally** used in Maven-based projects of https://logging.apache.org[the Apache Logging Services projects]. += Logging Parent -== Build +{project-name} is the parent project **internally** used in Maven-based projects of https://logging.apache.org[the Apache Logging Services]. -This project requires Java 17 for compilation. -You can build using `./mvnw verify` command. +include::features.adoc[] -== Usage +include::usage.adoc[] -See https://logging.apache.org/logging-parent[the website]. +[#development] +== Development +{project-name} uses {project-github-url}[GitHub] for source code management. + +The project requires a Java compiler matching the `{java-compiler-version}` range and targets Java `{java-target-version}`. + +You can build and verify sources using: + +[source,bash] +---- +./mvnw verify +---- + +You can build and view the website as follows: + +[source,bash] +---- +./mvnw -N site +python -m http.server -d target/site +---- + +[#distribution] == Distribution In accordance with the Apache Software Foundation's release https://infra.apache.org/release-distribution.html[distribution policy] and https://infra.apache.org/release-publishing.html[creation process], project artifacts are _officially_ accessible from the following locations: @@ -37,23 +57,30 @@ In accordance with the Apache Software Foundation's release https://infra.apache * ASF https://repository.apache.org/content/repositories/releases[Release] and https://repository.apache.org/content/repositories/snapshots[snapshot] repositories (mirrored to https://central.sonatype.dev/[the Maven Central Repository]) * ASF https://downloads.apache.org/logging/logging-parent[Distribution directory] -See xref:RELEASING.adoc[release instructions] for further details. +See xref:#release-instructions[the release instructions] for details. +[#support] == Support Please keep in mind that this project is intended for internal usage only. You can use GitHub Issues for feature requests and bug reports – not questions! See https://logging.apache.org/log4j/2.x/support.html[the Log4j support policy] for details. +[#security] == Security If you have encountered an unlisted security vulnerability or other unexpected behaviour that has security impact, please report them privately to mailto:[email protected][the Log4j security mailing list]. See https://logging.apache.org/log4j/2.x/security.html[the Log4j Security page] for further details. +include::release-notes.adoc[] + +include::release-instructions.adoc[] + +[#license] == License Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. -See xref:NOTICE.txt[] distributed with this work for additional information regarding copyright ownership. +See `NOTICE.txt` 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[]. diff --git a/RELEASING.adoc b/src/site/release-instructions.adoc similarity index 70% rename from RELEASING.adoc rename to src/site/release-instructions.adoc index 867709c..f15144b 100644 --- a/RELEASING.adoc +++ b/src/site/release-instructions.adoc @@ -24,24 +24,18 @@ limitations under the License. // Below instructions are shared by all Maven-based Apache Logging Services projects. // Be extremely cautious while making changes! -// Configuration /////////////////////////////////////////////////////////////// +include::_constants.adoc[] -// Name of the GitHub repository; `logging-parent`, `logging-log4j2`, `logging-log4j-tools`, etc. -:repository-name: logging-parent - -// Name of the project; `logging-parent`, `log4j`, `log4j-tools` -:project-name: logging-parent - -// Instructions //////////////////////////////////////////////////////////////// - -= Release instructions +[#release-instructions] +== Release instructions [WARNING] ==== In the code examples below, assuming the version to be released is `7.8.0`. ==== -== Stage the release +[#stage-release] +=== Stage the release . Create and push the release branch: + @@ -51,11 +45,11 @@ git fetch -p git checkout -B release/7.8.0 origin/main git push origin release/7.8.0 ---- -. Verify that the associated https://github.com/apache/{repository-name}/actions[GitHub Actions workflow] succeeds: +. Verify that the associated {project-github-url}/actions[GitHub Actions workflow] succeeds: .. `revision` property in `pom.xml` is updated .. Changelog is released (i.e., `src/changelog/7.8.0` folder is populated) .. *Signed artifacts* are uploaded to the _Staging Repositories_ in https://repository.apache.org/[repository.apache.org] -.. *Signed distribution and its checksum* (e.g., `apache-{project-name}-7.8.0-{bin,src}.{zip,.zip.asc,.zip.sha512}`) are uploaded to https://dist.apache.org/repos/dist/dev/logging/log4j[dist.apache.org/repos/dist/**dev**/logging/log4j] Subversion repository (along with auxiliary files; email texts, etc.) +.. *Signed distribution and its checksum* (e.g., `apache-{project-id}-7.8.0-{bin,src}.{zip,.zip.asc,.zip.sha512}`) are uploaded to https://dist.apache.org/repos/dist/dev/logging/{project-id}[dist.apache.org/repos/dist/**dev**/logging/{project-id}] Subversion repository (along with auxiliary files; website, email texts, etc.) + If not, commit necessary fixes, push, and repeat. @@ -68,9 +62,17 @@ You can iterate on the `release/7.8.0` branch to perfect it. ==== . _Close_ the repository in https://repository.apache.org/[repository.apache.org] -== Vote the release +[#stage-website] +=== Stage the website +. Check out the `asf-staging` branch of https://github.com/apache/logging-site[the `logging-site` repository] +. Add the contents of the generated website from the https://dist.apache.org/repos/dist/dev/logging/{project-id}[dist.apache.org/repos/dist/**dev**/logging/{project-id}] Subversion directory to `content/{project-id}` folder +. Commit and push your changes +. Verify the result in https://logging.staged.apache.org/{project-id} + +[#vote-release] +=== Vote the release -. Send the vote email uploaded to the https://dist.apache.org/repos/dist/dev/logging/log4j[dist.apache.org/repos/dist/**dev**/logging/log4j] Subversion repository +. Send the vote email uploaded to the https://dist.apache.org/repos/dist/dev/logging/{project-id}[dist.apache.org/repos/dist/**dev**/logging/{project-id}] Subversion repository + [WARNING] ==== @@ -90,13 +92,14 @@ If you are using GMail, simply enable the _"Plain text mode"_ while composing yo ---- Adding my +1. -With that, the release passes with 3 binding +1 votes from <PMC-member-1>, ..., <PMC-member-N>, and me. -I will continue the release process. +With that, the release passes with 3 binding +1 votes from <PMC-member-1>, ..., <PMC-member-N>, and me. I will continue the release process. ---- -== Publish the release +[#publish-release] +=== Publish the release -=== In the git repository +[#publish-release-git] +==== In the git repository . Pull the most recent changes and tags + @@ -129,25 +132,28 @@ git merge release/7.8.0 . Commit changes and push the `main` branch . Delete the local and remote copies of the `release/7.8.0` branch -=== In the ASF infrastructure +[#publish-release-asf] +==== In the ASF infrastructure . _Release_ the repository in https://repository.apache.org[repository.apache.org] -. In https://dist.apache.org/repos/dist/release/logging/{project-name}[dist.apache.org/repos/dist] Subversion repository, -.. create the `*release*/logging/{project-name}/7.8.0` folder, and copy the signed sources and their checksum from `*dev*/logging/{project-name}` to there -.. delete the folder from an earlier release in `*release*/logging/{project-name}` (stash the generated announcement email somewhere, you will need it later on) +. In https://dist.apache.org/repos/dist/release/logging/{project-id}[dist.apache.org/repos/dist] Subversion repository, +.. create the `*release*/logging/{project-id}/7.8.0` folder, and copy the signed sources and their checksum from `*dev*/logging/{project-id}` to there +.. delete the folder from an earlier release in `*release*/logging/{project-id}` (stash the generated announcement email somewhere, you will need it later on) .. commit changes . Report the release at https://reporter.apache.org/addrelease.html?logging[reporter.apache.org] -=== In GitHub +[#publish-release-github] +==== In GitHub -Once the artifacts are visible in https://central.sonatype.dev/[central.sonatype.dev], https://github.com/apache/{repository-name}/releases/new[create a new release in GitHub] +Once the artifacts are visible in https://central.sonatype.dev/[central.sonatype.dev], {project-github-url}/releases/new[create a new release in GitHub] . Use the `rel/7.8.0` tag . Copy release notes from the generated emails -== Announce the release +[#announce-release] +=== Announce the release -. Send the announcement email uploaded to the https://dist.apache.org/repos/dist/dev/logging/{project-name}[dist.apache.org/repos/dist/**dev**/logging/{project-name}] Subversion repository +. Send the announcement email uploaded to the https://dist.apache.org/repos/dist/dev/logging/{project-id}[dist.apache.org/repos/dist/**dev**/logging/{project-id}] Subversion repository + [WARNING] ==== diff --git a/src/antora/modules/ROOT/pages/release-notes/index.adoc b/src/site/release-notes.adoc similarity index 85% rename from src/antora/modules/ROOT/pages/release-notes/index.adoc rename to src/site/release-notes.adoc index d0a460f..fe442d8 100644 --- a/src/antora/modules/ROOT/pages/release-notes/index.adoc +++ b/src/site/release-notes.adoc @@ -22,13 +22,19 @@ ██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ███ ██ ██ ██ ██ ██ ████ ██ ██ ████ ██████ ██ - IF THIS FILE IS CALLED `index.adoc`, IT IS AUTO-GENERATED, DO NOT EDIT! + IF THIS FILE IS CALLED `index.adoc`, IT IS AUTO-GENERATED, DO NOT EDIT IT! Release notes `index.adoc` is generated from `src/changelog/.index.adoc.ftl`. Auto-generation happens during `generate-sources` phase of Maven. + Hence, you must always + + 1. Edit `.index.adoc.ftl` + 2. Run `./mvnw generate-sources` + 3. Commit both `.index.adoc.ftl` and the generated `.index.adoc` //// -= Release Notes +[#release-notes] +== Release Notes -include::10.x.x.adoc[10.x.x] -include::10.0.0.adoc[10.0.0] +include::release-notes/_10.x.x.adoc[] +include::release-notes/_10.0.0.adoc[] diff --git a/src/antora/modules/ROOT/pages/release-notes/10.0.0.adoc b/src/site/release-notes/_10.0.0.adoc similarity index 90% rename from src/antora/modules/ROOT/pages/release-notes/10.0.0.adoc rename to src/site/release-notes/_10.0.0.adoc index ea9842b..bb32225 100644 --- a/src/antora/modules/ROOT/pages/release-notes/10.0.0.adoc +++ b/src/site/release-notes/_10.0.0.adoc @@ -22,13 +22,21 @@ ██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ███ ██ ██ ██ ██ ██ ████ ██ ██ ████ ██████ ██ - IF THIS FILE DOESN'T HAVE A `.ftl` SUFFIX, IT IS AUTO-GENERATED, DO NOT EDIT! + IF THIS FILE DOESN'T HAVE A `.ftl` SUFFIX, IT IS AUTO-GENERATED, DO NOT EDIT IT! - Version-specific release notes (`7.8.0.adoc`, etc.) are generated from `src/changelog/.changelog.adoc.ftl`. + Version-specific release notes (`7.8.0.adoc`, etc.) are generated from `src/changelog/*/.release-notes.adoc.ftl`. Auto-generation happens during `generate-sources` phase of Maven. + Hence, you must always + + 1. Find and edit the associated `.release-notes.adoc.ftl` + 2. Run `./mvnw generate-sources` + 3. Commit both `.release-notes.adoc.ftl` and the generated `7.8.0.adoc` //// -== 10.0.0 (2023-09-08) +[#release-notes-10-0-0] +=== 10.0.0 + +Date:: 2023-09-08 This minor release contains various improvements that we expect to relieve the load on `pom.xml` and GitHub Actions workflows of Maven-based projects we parent. This is of particular importance while managing and cutting releases from multiple repositories. @@ -38,7 +46,7 @@ See https://github.com/apache/logging-log4j-tools/actions/runs/6120297528[this ` All preparations (release notes, source and binary distributions, vote & announcement emails, etc.) are staged to both Nexus and SVN and waiting the release manager to proceed. -=== Added +==== Added * Added `changelog-export` profile to easily export changelogs to Markdown files * Added `changelog-release` profile to easily move `src/changelog/.?.x.x` contents to their associated release directory @@ -49,6 +57,6 @@ All preparations (release notes, source and binary distributions, vote & announc * Added reusable GitHub Actions workflows to share CI boilerplate for other repositories * Switched to using `log4j-changelog-maven-plugin` for managing changelog and release notes -=== Changed +==== Changed * Switched to semantic versioning (old version: `9`, new version: `10.0.0`) diff --git a/src/antora/modules/ROOT/pages/release-notes/10.x.x.adoc b/src/site/release-notes/_10.x.x.adoc similarity index 65% rename from src/antora/modules/ROOT/pages/release-notes/10.x.x.adoc rename to src/site/release-notes/_10.x.x.adoc index 7332533..c4278af 100644 --- a/src/antora/modules/ROOT/pages/release-notes/10.x.x.adoc +++ b/src/site/release-notes/_10.x.x.adoc @@ -22,31 +22,33 @@ ██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ███ ██ ██ ██ ██ ██ ████ ██ ██ ████ ██████ ██ - IF THIS FILE DOESN'T HAVE A `.ftl` SUFFIX, IT IS AUTO-GENERATED, DO NOT EDIT! + IF THIS FILE DOESN'T HAVE A `.ftl` SUFFIX, IT IS AUTO-GENERATED, DO NOT EDIT IT! - Version-specific release notes (`7.8.0.adoc`, etc.) are generated from `src/changelog/.changelog.adoc.ftl`. + Version-specific release notes (`7.8.0.adoc`, etc.) are generated from `src/changelog/*/.release-notes.adoc.ftl`. Auto-generation happens during `generate-sources` phase of Maven. -//// + Hence, you must always -== 10.x.x + 1. Find and edit the associated `.release-notes.adoc.ftl` + 2. Run `./mvnw generate-sources` + 3. Commit both `.release-notes.adoc.ftl` and the generated `7.8.0.adoc` +//// -This minor release contains various improvements that we expect to relieve the load on `pom.xml` and GitHub Actions workflows of Maven-based projects we parent. -This is of particular importance while managing and cutting releases from multiple repositories. -See `README.adoc` for the complete list of features and their usage. +[#release-notes-10-x-x] +=== 10.x.x -See [this `logging-log4j-tools` GitHub Actions workflow run](https://github.com/apache/logging-log4j-tools/actions/runs/6120297528) demonstrating a successful release cut using a SNAPSHOT version of this `logging-parent` release. -All preparations (release notes, distribution ZIP, vote & announcement emails, etc.) are staged to both Nexus and SVN and waiting the release manager to proceed. +This minor release focuses on shipping AsciiDoc-based website generation convenience targeting the `src/site` folder. +As a part of this effort, `logging-parent` started publishing https://logging.apache.org/logging-parent[its own website] and `log4j-changelog` support is switched from Markdown to AsciiDoc. -=== Added +==== Added -* Added `antora` and `antora-tmpl-yml` profiles to generate Antora-based websites from `src/antora` -* Added `bootstrap` profile to download support files from `logging-parent` +* Added `asciidoc` and `constants-tmpl-adoc` profiles to generate AsciiDoc-based websites from `src/site` +* Started publishing https://logging.apache.org/logging-parent[the project website] -=== Changed +==== Changed * Switched the default `log4j-changelog` configuration from Markdown (`.release-notes.md.ftl` and `.index.md.ftl`) to AsciiDoc (`.release-notes.adoc.ftl` and `.index.adoc.ftl`) -=== Removed +==== Removed -* Removed `project.build.outputTimestamp` override since it is already provided by the parent POM and its old value `0` was causing reproducibility issues for `spring-boot:repackage` +* Removed `project.build.outputTimestamp` override since it is already provided by the parent POM and its old value `0` was causing https://github.com/spring-projects/spring-boot/pull/37438[reproducibility issues] for `spring-boot:repackage` diff --git a/src/antora/modules/ROOT/nav.adoc b/src/site/usage.adoc similarity index 64% rename from src/antora/modules/ROOT/nav.adoc rename to src/site/usage.adoc index 1cbb229..9e1cd0b 100644 --- a/src/antora/modules/ROOT/nav.adoc +++ b/src/site/usage.adoc @@ -14,6 +14,21 @@ See the License for the specific language governing permissions and limitations under the License. //// -* xref:index.adoc[Basics] -* xref:release-notes/index.adoc[] -* {project-scm-url}[Source code repository] + +include::_constants.adoc[] + +[#usage] +== Usage + +You can use {project-name} as follows: + +. Add `org.apache.logging:logging-parent:{project-version}` as a `parent` to your `pom.xml` +.. Check if `./mvnw verify` succeeds, otherwise make necessary changes +. Copy and adapt the support files (`.gitignore`, `.github/workflows/build.yaml`, etc.) +. Check out your website: ++ +[source,bash] +---- +./mvnw -N site +python -m http.server -d target/site +----
