diff --git a/BUILDING.adoc b/BUILDING.adoc index 0148c93c452..27d76641b68 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] ---- @@ -84,6 +78,13 @@ You either need to have a user-level configuration in `~/.m2/toolchains.xml` or ---- +. 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 index 7453e67fd77..abcc645e4e2 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 00000000000..cf6bff43162 --- /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 + +`-site-`:: +`-site--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/`:: +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 95f2242cdfe..00000000000 --- 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/..x.x/_.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 -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.