You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by pk...@apache.org on 2023/04/28 17:50:04 UTC
[logging-log4j-transform] 02/02: Improve documentation
This is an automated email from the ASF dual-hosted git repository.
pkarwasz pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/logging-log4j-transform.git
commit e539812a721a844e191e7ed0fce8dfa57e02d818
Author: Piotr P. Karwasz <pi...@karwasz.org>
AuthorDate: Fri Apr 28 19:49:53 2023 +0200
Improve documentation
---
README.adoc | 23 ++++
RELEASING.adoc | 125 +++++++++++++++++++++
log4j-transform-maven-plugin/README.adoc | 28 ++++-
.../README.adoc | 2 +-
4 files changed, 176 insertions(+), 2 deletions(-)
diff --git a/README.adoc b/README.adoc
index d46ad07..5b9108f 100644
--- a/README.adoc
+++ b/README.adoc
@@ -23,6 +23,29 @@ a bytecode weaver that improves logging performance by precomputing the location
xref:log4j-transform-maven-shade-plugin-extensions/README.adoc[`log4j-transform-maven-shade-plugin-extensions`]::
a https://maven.apache.org/plugins/maven-shade-plugin/examples/resource-transformers.html[resource transformer] for the Apache Maven Shade Plugin that allows you to use additional Log4j 2.x Core component modules.
+== Build
+
+This project generates Java 8 bytecode, though requires Java 11 for compilation.
+You can build and test sources using `./mvnw verify` command.
+
+== 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/log4j-transform[Distribution directory]
+
+See xref:RELEASING.adoc[release instructions] for further details.
+
+== Support
+
+You can use GitHub Issues for feature requests and bug reports – not questions!
+For the rest, you can use mailto:security@logging.apache.org[the Log4j development mailing list].
+
+== Security
+
+If you have encountered an unlisted security vulnerability or other unexpected behaviour that has security impact, please report them privately to mailto:security@logging.apache.org[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.
diff --git a/RELEASING.adoc b/RELEASING.adoc
new file mode 100644
index 0000000..19d78d3
--- /dev/null
+++ b/RELEASING.adoc
@@ -0,0 +1,125 @@
+////
+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 instructions
+
+[WARNING]
+====
+In the code examples below, assuming the version to be released is `7.8.0`.
+====
+
+== Stage the release artifacts
+
+. Checkout the release branch: `git checkout -B release/7.8.0 origin/master`
+. Perform and commit following changes:
+.. Set the `revision` property to `7.8.0` in xref:pom.xml[`pom.xml`]
+.. Update the version and date in xref:CHANGELOG.adoc[`CHANGELOG.adoc`]
+. Make sure that `./mvnw clean verify` succeeds – if not, commit necessary fixes
+. Push the `release/7.8.0` branch
+. Run `./mvnw clean deploy`
+. Run:
+[source,console]
+----
+ZIP_FILEPATH="/tmp/apache-log4j-transform-7.8.0-src.zip"
+git ls-files -z | xargs -0 zip -9 "$ZIP_FILEPATH" --
+gpg --armor --detach-sign "$ZIP_FILEPATH"
+sha512sum "$ZIP_FILEPATH" > "$ZIP_FILEPATH.sha512"
+----
+. _Close_ the repository in https://repository.apache.org/[repository.apache.org]
+. Commit _the signed sources and their checksum_ (e.g., `apache-log4j-transform-7.8.0-src.{zip,.zip.asc,.zip.sha512}`) to https://dist.apache.org/repos/dist/dev/logging/log4j[dist.apache.org/repos/dist/**dev**/logging/log4j] Subversion repository and delete any artifacts from old releases
+
+== Vote the release
+
+Collect release votes via email using the following template:
+
+.`[VOTE] Release Apache Log4j Transformation Tools 7.8.0` titled email to `dev@logging.apache.org`
+[source]
+----
+The Apache Log4j Transformation Tools 7.8.0 release is now available for voting.
+
+This release contains minor enhancements and bug fixes.
+
+Source repository: https://github.com/apache/logging-log4j-transform
+Tag: rel/7.8.0-rc1
+Commit: e82a44142280d013bd76ea18951fde00dcee192b
+Artifacts: https://dist.apache.org/repos/dist/dev/logging/log4j/
+Nexus repository: https://repository.apache.org/content/repositories/orgapachelogging-1096
+Signing key: https://keyserver.ubuntu.com/pks/lookup?search=077e8893a6dcc33dd4a4d5b256e73ba9a0b592d0&fingerprint=on&op=index
+
+Please download, test, and cast your votes on the Log4j developers list.
+
+[ ] +1, release the artifacts
+[ ] -1, don't release, because...
+
+The vote will remain open for 72 hours (or more if required). All votes are welcome and we encourage everyone to test the release, but only the Logging Services PMC votes are officially counted. At least 3 +1 votes and more positive than negative votes are required.
+----
+
+[WARNING]
+====
+Make sure your email is sent in plain text, that is, https://infra.apache.org/contrib-email-tips#nohtml[no HTML]!
+If you are using GMail, simply enable the _"Plain text mode"_ while composing your message.
+====
+
+Once the consensus is reached within the set time frame, respond to the first post in the thread as follows:
+
+[source]
+----
+Adding my +1.
+
+With that, the release passes with 3 binding +1 votes from A, B and me.
+----
+
+== Publish the release
+
+=== In git repository
+
+. Pull the most recent changes and tags
+. Tag the release (e.g., `rel/7.8.0`) and push it
++
+[IMPORTANT]
+====
+The ASF infrastructure treats ``rel/``-prefixed git tags special and ensures they are immutable for provenance reasons.
+====
+. Rebase `release/7.8.0` changes to `main`
+. Set the revision property to the next development version (e.g., `7.9.0-SNAPSHOT`) in xref:pom.xml[`pom.xml`]
+. Commit changes and push the `main` branch
+. Delete the local and remote copies of the `release/7.8.0` branch
+
+=== In the ASF infrastructure
+
+. _Release_ the repository in https://reporter.apache.org/addrelease.html?logging[repository.apache.org]
+. In https://dist.apache.org/repos/dist/release/logging/log4j[dist.apache.org/repos/dist] Subversion repository,
+.. move the signed sources and their checksum from `*dev*/logging/log4j` directory to `*release*/logging/log4j-tools/7.8.0`
+.. delete the folder from an earlier release in `*release*/logging/log4j-tools`
+.. commit changes
+. Report the release at https://reporter.apache.org/[reporter.apache.org]
+
+=== In GitHub
+
+Once the artifacts are visible in https://central.sonatype.dev/[central.sonatype.dev], https://github.com/apache/logging-log4j-tools/releases/new[create a new release in GitHub]
+
+. Use the `rel/7.8.0` tag
+. Copy necessary changes from xref:CHANGELOG.adoc[`CHANGELOG.adoc`]
+.. formatting needs to be converted from AsciiDoc to https://github.github.com/gfm/[GitHub Flavored Markdown]
+.. GitHub Issue links need to be converted from
++
+[source]
+----
+https://github.com/apache/logging-log4j-transform/issues/19[#19]
+----
++
+AsciiDoc-formatted links to simply `#19`
diff --git a/log4j-transform-maven-plugin/README.adoc b/log4j-transform-maven-plugin/README.adoc
index b0d5f56..46442d6 100644
--- a/log4j-transform-maven-plugin/README.adoc
+++ b/log4j-transform-maven-plugin/README.adoc
@@ -19,6 +19,32 @@
The Transform Plugin is used to postprocess the compiled classes of your project and replace all Log4j 2.x API calls with https://logging.apache.org/log4j/2.x/log4j-api/apidocs/org/apache/logging/log4j/LogBuilder.html[`LogBuilder`] calls with a statically precomputed location.
This allows you to use location information in your logs without incurring in the *expensive* runtime calls usually used to acquire it.
+== How it works
+
+The working principle is very simple: every call to the Log4j 2.x API like
+[source,java]
+----
+public void helloLog() {
+ logger.info(MarkerManager.getMarker("NET"), "Sending {} bytes of data.", 1000);
+}
+----
+is rewritten at a bytecode levelinto an equivalent `LogBuilder` call:
+[source,java]
+----
+private static final StackTraceElement[] locations = {
+ new StackTraceElement("org.apache.logging.log4j.HelloWorld", "HelloWorld.java", "helloLog", 1234)
+};
+
+public void helloLog() {
+ logger.atInfo()
+ .withLocation(locations[0])
+ .withMarker(MarkerManager.getMarker("NET"))
+ .log("Sending {} bytes of data.", 1000);
+}
+----
+
+In the current implementation locations are stored in classes whose name ends in `$$Log4j2$$Cache`, so they can not accidentally be used by XML/JSON serializers.
+
== Goals
This plugin consists of a single goal:
@@ -32,7 +58,7 @@ To use the plugin you need to declare a dependency on https://central.sonatype.c
Add the following configuration to your POM file:
-[xml]
+[source,xml]
----
<project>
[...]
diff --git a/log4j-transform-maven-shade-plugin-extensions/README.adoc b/log4j-transform-maven-shade-plugin-extensions/README.adoc
index 6e4a540..3495668 100644
--- a/log4j-transform-maven-shade-plugin-extensions/README.adoc
+++ b/log4j-transform-maven-shade-plugin-extensions/README.adoc
@@ -32,7 +32,7 @@ This resource transformer is usually used together with the `ManifestResourceTra
A typical configuration is:
-[xml]
+[source,xml]
----
<project>
[...]