apache · vy · Apr 30, 2024 · Apr 30, 2024 · Apr 30, 2024
diff --git a/BUILDING.adoc b/BUILDING.adoc
@@ -55,19 +55,13 @@ printf '127.0.0.1 %s\n::1 %s\n' `hostname` `hostname` | sudo tee -a /etc/hosts
 [#java8-tests]
 === Java 8 tests
 
-To test the library against the target JRE (JRE 8), you need to configure a JDK 8 toolchains as explained below and run Maven with the `java8-tests` profile:
-
-[source,bash]
-----
-./mvnw verify -Pjava8-tests
-----
+You can run tests using the target JRE (i.e., JRE 8) as follows:
 
 [#toolchains]
-=== Configuring Maven Toolchains
-
-Maven Toolchains is used to employ additional JDKs required for tests.
+. Maven Toolchains is used to employ additional JDKs required for tests.
 You either need to have a user-level configuration in `~/.m2/toolchains.xml` or explicitly provide one to the Maven: `./mvnw --global-toolchains /path/to/toolchains.xml`.
-
++
+.An example `toolchains.xml` containing a JDK 8 toolchain
 [source,xml]
 ----
 <?xml version="1.0" encoding="UTF8"?>
@@ -84,6 +78,13 @@ You either need to have a user-level configuration in `~/.m2/toolchains.xml` or
 </toolchains>
 ----
 
+. Run Maven tests with the `java8-tests` profile:
++
+[source,bash]
+----
+./mvnw verify -Pjava8-tests,!java8-incompat-fixes
+----
+
 [#website]
 == Building the website
 
@@ -105,15 +106,48 @@ You can view the generated website with a browser by pointing it to `target/site
 
 You can follow below steps for casual development needs:
 
-. Make sure you installed everything: `./mvnw install -DskipTests`
-. After making a change to, say, `log4j-core`, install your changes: `./mvnw install -pl :log4j-core -DskipTests`
-. Run all tests associated with `log4j-core`: `./mvnw test -pl :log4j-core-test`
-. Run a particular test: `./mvnw test -pl :log4j-core-test -Dtest=FooBarTest`
+. Make sure you installed everything:
++
+[source,bash]
+----
+./mvnw install -DskipTests
+----
+
+. After making a change to, say, `log4j-core`, install your changes:
++
+[source,bash]
+----
+./mvnw install -pl :log4j-core -DskipTests
+----
+
+. Run all tests associated with `log4j-core`:
++
+[source,bash]
+----
+./mvnw test -pl :log4j-core-test
+----
+
+. Run a particular test:
++
+[source,bash]
+----
+./mvnw test -pl :log4j-core-test -Dtest=FooBarTest
+----
+
+. Make sure all build checks (Spotless, Spotbugs, BND, RAT, etc.) succeed:
++
+[source,bash]
+----
+./mvnw verify -DskipTests -pl :log4j-core,:log4j-core-test
+----
 
+[TIP]
+====
 You can connect your IDE to a `./mvnw test` run by
 
 . Run `./mvnw test -pl :log4j-core-test -Dtest=FooBarTest -Dmaven.surefire.debug`
 . Use _"Run > Attach to process"_ in IntelliJ IDEA
+====
 
 [#development-faq]
 === F.A.Q

diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc
@@ -57,6 +57,7 @@
 * xref:javadoc.adoc[Java API reference]
 * xref:articles.adoc[Articles]
 * xref:faq.adoc[F.A.Q.]
+* xref:development.adoc[]
 
 .Components
 * xref:log4j-api.adoc[]

diff --git a/src/site/antora/modules/ROOT/pages/development.adoc b/src/site/antora/modules/ROOT/pages/development.adoc
@@ -0,0 +1,109 @@
+////
+    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.
+////
+
+= Development
+
+This page shares information related to the development of Log4j.
+Content is aimed for users who want to contribute source code patches and maintainers.
+
+[TIP]
+====
+Do you need help for setting up or configuring Log4j?
+Please refer to {logging-services-url}/support.html[the Support page] instead.
+====
+
+[#github]
+== GitHub setup
+
+Log4j uses GitHub extensively:
+
+Source code repository:: {project-github-url}[]
+Issue tracker:: {project-github-url}/issues[]
+Discussions::
+{project-github-url}/discussions[]
++
+[TIP]
+====
+Maintainer discussions mostly take place in mailing lists.
+Please refer to {logging-services-url}/support.html[the Support page] for the complete list of communication channels.
+====
+
+[#branching]
+== Branching scheme
+
+The following branching scheme is followed:
+
+`2.x`:: The most recent Log4j 2 code
+
+`main`:: The most recent Log4j 3 code
+
+`<sourceBranch>-site-<environment>`::
+`<sourceBranch>-site-<environment>-out`::
+Branches used to serve the staging and production websites.
+`out`-suffixed ones are automatically populated by CI, you are not supposed to touch them.
+See {logging-services-url}/logging-parent/usage.html#website[the Logging Parent website] for details.
+
+`release/<version>`::
+Branch triggering the CI logic to start {logging-services-url}/logging-parent/release-instructions-project.html[the release process]
+
+[#building]
+== How can I build Log4j from sources?
+
+See {project-github-url}/tree/2.x/BUILDING.adoc[the build instructions].
+
+[#contributor]
+== I am **not** a committer. How shall I submit a patch?
+
+. Is this a _trivial fix_ such as code or documentation typo?
+Simply submit a pull request.
+Changelog entry is not needed and make sure `./mvnw verify site` succeeds.
+
+. Is this a _non-trivial fix_ or a _new feature_?
+Pitch it in a {logging-services-url}/support.html#discussions-maintainer[maintainer discussion channel] and ask for assistance.
+
+[#committer]
+== I am a committer. How shall I push my changes?
+
+. Is it something trivial?
+Go ahead and push it.
+
+. Otherwise, submit a pull request.
+Make sure a changelog entry is attached and `./mvnw verify site` succeeds.
++
+[TIP]
+====
+You are strongly advised to spar with another maintainer first (see {logging-services-url}/support.html#discussions-maintainer[maintainer discussion channels]) before starting to code.
+====
+
+[#release-project]
+== I am a PMC member. How do I make a new release?
+
+All Maven-based Logging Services projects are parented by {logging-services-url}/logging-parent[Logging Parent], which streamlines several project-wide processes, including making a new release.
+See {logging-services-url}/logging-parent/release-instructions-project.html[its release instructions for projects].
+
+[#release-xml-schema]
+== I am a PMC member. How do I publish a new XML schema?
+
+All Maven-based Logging Services projects are parented by {logging-services-url}/logging-parent[Logging Parent], which streamlines several project-wide processes, including publishing XML schemas.
+See {logging-services-url}/logging-parent/release-instructions-xml-schema.html[its release instructions for XML schemas].
+
+[WARNING]
+====
+**Projects and XML schemas have different lifecycles!**
+A new release of a project does not necessarily mean a new release of its XML schemas.
+XML schemas might have been untouched, or they might contain minor changes while the project itself contains breaking changes, etc.
+====