You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by vy...@apache.org on 2024/04/30 13:27:29 UTC
(logging-log4j2) 01/01: Add a new `Development` page
This is an automated email from the ASF dual-hosted git repository.
vy pushed a commit to branch feature/2.x/development-page
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 31890787cbefb7aac98aa04e5a67758d37e7692a
Author: Volkan Yazıcı <vo...@yazi.ci>
AuthorDate: Tue Apr 30 15:27:32 2024 +0200
Add a new `Development` page
---
BUILDING.adoc | 62 +++-
src/site/antora/modules/ROOT/nav.adoc | 1 +
.../antora/modules/ROOT/pages/development.adoc | 109 ++++++
src/site/antora/modules/ROOT/pages/guidelines.adoc | 381 ---------------------
4 files changed, 158 insertions(+), 395 deletions(-)
diff --git a/BUILDING.adoc b/BUILDING.adoc
index 0148c93c45..43834ff1ce 100644
--- 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
+----
+
[#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
index 7453e67fd7..abcc645e4e 100644
--- 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
new file mode 100644
index 0000000000..cf6bff4316
--- /dev/null
+++ 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.
+====
diff --git a/src/site/antora/modules/ROOT/pages/guidelines.adoc b/src/site/antora/modules/ROOT/pages/guidelines.adoc
deleted file mode 100644
index 95f2242cdf..0000000000
--- a/src/site/antora/modules/ROOT/pages/guidelines.adoc
+++ /dev/null
@@ -1,381 +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.
-////
-= Apache Log4j Project Guidelines
-
-This document defines the guidelines for the
-https://logging.apache.org/log4j/2.x[Apache Log4j Project]. It includes
-definitions of how conflict is resolved by voting, who is able to vote,
-the procedures to follow for proposing and making changes as well as
-guidelines for changing code.
-
-The objective here is to avoid unnecessary conflict over changes and
-continue to produce a quality system in a timely manner. Not all
-conflict can be avoided, but at least we can agree on the procedures for
-conflict to be resolved.
-
-[#people-places-and-things]
-== People, Places, and Things
-
-Apache Logging Project Management Committee::
-The group of volunteers who are responsible for managing the Apache
-Logging Projects, including Log4j. This includes deciding what is
-distributed as products of the Apache Logging Project, maintaining the
-Project's shared resources, speaking on behalf of the Project,
-resolving license disputes regarding Apache products, nominating new
-PMC members or committers, and establishing these guidelines.
-+
-Membership in the Apache Logging PMC is by invitation only and must be
-approved by consensus of the active Logging PMC members. A PMC member is
-considered inactive by their own declaration or by not contributing in
-any form to the project for over six months. An inactive member can
-become active again by reversing whichever condition made them inactive
-( _i.e._ , by reversing their earlier declaration or by once again
-contributing toward the project's work). Membership can be revoked by a
-unanimous vote of all the active PMC members other than the member in
-question.
-
-Apache Logging Committers::
-The group of volunteers who are responsible for the technical aspects
-of the Apache Logging Projects. This group has write access to the
-appropriate source repositories and these volunteers may cast binding
-votes on any technical discussion. Although a committer usually joins
-due to their activity on one of the Logging projects, they will have
-commit access to all Logging projects.
-+
-Membership as a Committer is by invitation only and must be approved by
-consensus of the active Logging PMC members. A Committer is considered
-inactive by their own declaration or by not contributing in any form to
-the project for over six months. An inactive member can become active
-again by reversing whichever condition made them inactive ( _i.e._ , by
-reversing their earlier declaration or by once again contributing toward
-the project's work). Membership can be revoked by a unanimous vote of
-all the active PMC members (except the member in question if they are a
-PMC member).
-
-Log4j Developers::
-All of the volunteers who are contributing time, code, documentation,
-or resources to the Log4j Project. A developer that makes sustained,
-welcome contributions to the project for over six months is usually
-invited to become a Committer, though the exact timing of such
-invitations depends on many factors.
-
-mailing list::
-The Log4j developers' primary mailing list for discussion of issues
-and changes related to the project ( _dev@logging.apache.org_ ).
-Subscription to the list is open, but only subscribers can post
-directly to the list.
-
-private list::
-The Logging PMC's private mailing list for discussion of issues that
-are inappropriate for public discussion, such as legal, personal, or
-security issues prior to a published fix. Subscription to the list is
-only open (actually: mandatory) to Apache Logging's Project Management
-Committee.
-
-Git::
-All of the Apache products are maintained in information repositories
-using either Subversion or Git; Log4j uses Git.
-Only some of the Apache developers have write access to the Apache Logging repositories; everyone has read access.
-
-[#issues]
-== Issue Management
-
-The Log4j project uses https://github.com/apache/logging-log4j2/issues[GitHub Issues] for its issue tracking system.
-
-Many issues will be encountered by the project, each resulting in zero
-or more proposed action items. Issues should be raised on the mailing
-list as soon as they are identified. Action items *must* be raised on
-the mailing list and added to the issue tracker using the appropriate issue type. All
-action items may be voted on, but not all of them will require a formal
-vote.
-
-[#voting]
-== Voting
-
-Any of the Log4j Developers may vote on any issue or action item.
-However, the only binding votes are those cast by active members of the
-Apache Logging PMC; if the vote is about a change to source code or
-documentation, the primary author of what is being changed may also cast
-a binding vote on that issue. All other votes are non-binding. All
-developers are encouraged to participate in decisions, but the decision
-itself is made by those who have been long-time contributors to the
-project. In other words, the Apache Log4j Project is a minimum-threshold
-meritocracy.
-
-The act of voting carries certain obligations -- voting members are not
-only stating their opinion, they are agreeing to help do the work of the
-Log4j Project. Since we are all volunteers, members often become
-inactive for periods of time in order to take care of their "real jobs"
-or devote more time to other projects. It is therefore unlikely that the
-entire group membership will vote on every issue. To account for this,
-all voting decisions are based on a minimum quorum.
-
-Each vote can be made in one of three flavors:
-
-+1::
-Yes, agree, or the action should be performed. On some issues, this
-vote is only binding if the voter has tested the action on their own
-system(s).
-±0::
-Abstain, no opinion, or I am happy to let the other group members
-decide this issue. An abstention may have detrimental effects if too
-many people abstain.
--1::
-No. On issues where consensus is required, this vote counts as a
-*veto*. All vetoes must include an explanation of why the veto is
-appropriate. A veto with no explanation is void. No veto can be
-overruled. If you disagree with the veto, you should lobby the person
-who cast the veto. Voters intending to veto an action item should make
-their opinions known to the group immediately, so that the problem can
-be remedied as early as possible.
-
-An action item requiring _consensus approval_ must receive at least *3
-binding +1* votes and *no vetoes*. An action item requiring _majority
-approval_ must receive at least *3 binding +1* votes and more *+1* votes
-than *-1* votes ( _i.e._ , a majority with a minimum quorum of three
-positive votes). All other action items are considered to have _lazy
-approval_ until someone votes *-1* , after which point they are decided
-by either consensus or a majority vote, depending upon the type of
-action item.
-
-[#types-of-action-items]
-== Types of Action Items
-
-Long Term Plans::
-Long term plans are simply announcements that group members are
-working on particular issues related to the Log4j software. These are
-not voted on, but group members who do not agree with a particular
-plan, or think an alternate plan would be better, are obligated to
-inform the group of their feelings. In general, it is always better to
-hear about alternate plans *prior* to spending time on less adequate
-solutions.
-Short Term Plans::
-Short term plans are announcements that a developer is working on a
-particular set of documentation or code files, with the implication
-that other developers should avoid them or try to coordinate their
-changes. This is a good way to proactively avoid conflict and possible
-duplication of work.
-Release Plan::
-A release plan is used to keep all the developers aware of when a
-release is desired, who will be the release manager, when the
-repository will be frozen in order to create the release, and assorted
-other trivia to keep us from tripping over ourselves during the final
-moments. Lazy majority (at least 3 x +1 and more +1 than -1) decides
-each issue in the release plan.
-Release Testing::
-After a new release is built it must be tested before being released
-to the public. Majority approval is required before the distribution
-can be publicly released.
-Showstoppers/Blockers::
-Showstoppers are issues that require a fix be in place before the next
-public release. They are listed in the issue tracking system in order to focus special
-attention on the problem. An issue becomes a showstopper when it is
-listed as such in the issue tracking system and remains so by lazy consensus.
-
-All product changes to the currently active repository are subject to
-lazy consensus. All product changes to a prior-branch (old version)
-repository require consensus before the change is committed.
-
-[#when-to-commit-a-change]
-== When to Commit a Change
-
-Ideas must be review-then-commit; patches can be commit-then-review.
-With a commit-then-review process, we trust that the developer doing the
-commit has a high degree of confidence in the change. Doubtful changes,
-new features, and large-scale overhauls need to be discussed before
-being committed to a repository. Any change that affects the semantics
-of arguments to configurable directives, significantly adds to the
-runtime size of the program, or changes the semantics of an existing API
-function must receive consensus approval on the mailing list before
-being committed.
-
-Each developer is responsible for notifying the mailing list and adding
-an action item to the issue tracking system when they have an idea for a new feature or major
-change to propose for the product. The distributed nature of the Log4j
-project requires an advance notice of 48 hours in order to properly
-review a major change -- consensus approval of either the concept or a
-specific patch is required before the change can be committed. Note that
-a member might veto the concept (with an adequate explanation), but
-later rescind that veto if a specific patch satisfies their objections.
-No advance notice is required to commit singular bug fixes.
-
-Related changes should be committed as a group, or very closely
-together. Half-completed projects should not be committed unless doing
-so is necessary to pass the baton to another developer who has agreed to
-complete the project in short order. All code changes must be
-successfully compiled and unit tests pass on the developer's platform
-before being committed.
-
-The current source code tree should be capable of complete compilation
-at all times. However, it is sometimes impossible for a developer on one
-platform to avoid breaking some other platform when a change is
-committed, particularly when completing the change requires access to a
-special development tool on that other platform. If it is anticipated
-that a given change will break some other platform, the committer must
-indicate that in the commit log.
-
-The committer is responsible for the quality of any third-party code or
-documentation they commit to the repository. All software committed to
-the repository must be covered by the Apache LICENSE or contain a
-copyright and license that allows redistribution under the same
-conditions as the Apache LICENSE.
-
-A committed change must be reversed if it is vetoed by one of the voting
-members and the veto conditions cannot be immediately satisfied by the
-equivalent of a "bug fix" commit. The veto must be rescinded before the
-change can be included in any public release.
-
-[#changelogs]
-== Changelog and Git logs
-
-Many code changes should be noted in a `src/changelog/.<releaseMajorVersion>.x.x/<issueId>_<shortSummary>.xml` file, and all
-should be documented in Git commit messages. Often the text of the Git
-log and the changelog entry are the same, but the distinct
-requirements sometimes result in different information.
-
-[#subversion-log]
-=== Git log
-
-The Git commit log message contains any information needed by
-
-* fellow developers or other people researching source code
-changes/fixes
-* end users (at least point out what the implications are for end users;
-it doesn't have to be in the most user friendly wording)
-
-If the code change was provided by a non-committer, attribute it using
-Submitted-by. If the change was committed verbatim, identify the
-committer(s) who reviewed it with Reviewed-by. If the change was
-committed with modifications, use the appropriate wording to document
-that, perhaps "committed with changes" if the person making the commit
-made the changes, or "committed with contributions from xxxx" if others
-made contributions to the code committed.
-
-Example log message:
-
-....
-LOG4J2-9999
-Check the return code from parsing the content length, to avoid a
-crash if requests contain an invalid content length.
-Submitted by: Jane Doe <janedoe example.com>
-Reviewed by: susiecommitter
-....
-
-[#changes]
-=== Changelog
-
-Changelog is a subset of the information that end users need to see
-when they upgrade from one release to the next:
-
-* what can I now do that I couldn't do before
-* what problems that we anticipate a user could have suffered from are
-now fixed
-* all security fixes included, with CVE number. (If not available at the
-time of the commit, add later.)
-
-All entries in changelog should include the appropriate issue
-ID and should credit contributions made by non-committers by
-referencing them in the due-to attribute even if modifications needed to
-be made to the contribution.
-
-The attribution for the change is anyone responsible for the code
-changes.
-
-[#committing-security-fixes]
-== Committing Security Fixes
-
-Open source projects, ASF or otherwise, have varying procedures for
-commits of vulnerability fixes. One important aspect of these procedures
-is whether or not fixes to vulnerabilities can be committed to a
-repository with commit logs and possibly CHANGES entries which
-purposefully obscure the vulnerability and omit any available
-vulnerability tracking information. The Apache HTTP Server project has
-decided that it is in the best interest of our users that the initial
-commit of such code changes to any branch will provide the best
-description available at that time as well as any available tracking
-information such as CVE number. Committing of the fix will be delayed
-until the project determines that all of the information about the issue
-can be shared.
-
-In some cases there are very real benefits to sharing code early even if
-full information about the issue cannot, including the potential for
-broader review, testing, and distribution of the fix. This is outweighed
-by the concern that sharing only the code changes allows skilled
-analysts to determine the impact and exploit mechanisms but does not
-allow the general user community to determine if preventative measures
-should be taken.
-
-If a vulnerability is partially disclosed by committing a fix before the
-bug is determined to be exploitable, the httpd security team will decide
-on a case by case basis when to document the security implications and
-tracking number.
-
-[#patch]
-== Patch Format
-
-When a specific change to the software is proposed for discussion or
-voting on the mailing list, it should be presented in the form of input
-to the patch command. When sent to the mailing list, the message should
-contain a Subject beginning with `[PATCH]` and a distinctive one-line
-summary corresponding to the action item for that patch. Afterwords, the
-patch summary in the STATUS file should be updated to point to the
-Message-ID of that message.
-
-The patch should be created by using the diff -u command from the
-original software file(s) to the modified software file(s). E.g.,
-`diff -u http_main.c.orig http_main.c >> patchfile.txt` or
-`svn diff http_main.c >> patchfile.txt` All patches necessary to address
-an action item should be concatenated within a single patch message. If
-later modification of the patch proves necessary, the entire new patch
-should be posted and not just the difference between two patches. The
-STATUS file entry should then be updated to point to the new patch
-message.
-
-The completed patchfile should produce no errors or prompts when the
-command, `patch -s < patchfile` is issued in the target repository.
-
-[#teamwork]
-== Teamwork
-
-Open source projects function best when everyone is aware of the "rules
-of the road" and abide by them.
-
-1. Error on the side of caution. If you don’t understand it, don’t
-touch it and ask on the list. If you think you understand it read it
-again or ask until you are sure you do. Nobody will blame you for asking
-questions.
-2. Don’t break the build - if there is the slightest chance the change
-you are making could cause unit test failures, run all unit tests.
-Better yet, get in the habit of always running the unit tests before
-doing the commit.
-3. If the build breaks and you have made recent changes then assume you
-broke it and try to fix it. Although it might not have been something
-you did it will make others feel a lot better than having to fix the
-mistake for you. Everyone makes mistakes. Taking responsibility for them
-is a good thing.
-4. Don’t change things to match your personal preference - the project
-has link:javastyle.html[style guidelines] that are validated with
-checkstyle, PMD, and other tools. If you aren't fixing a bug, fixing a
-problem identified by the tools, or fixing something specifically called
-out in these guidelines then start a discussion to see if the change is
-something the project wants before starting to work on it. We try to
-discuss things first and then implement the consensus reached in the
-discussion.
-5. Along the same lines, do not commit automatic changes made by your
-IDE without reviewing them. There are a few places in the code that
-cannot conform to style guidelines without causing errors in some
-environments. These are clearly marked and must be left as is.