| //// |
| 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. |
| //// |
| = 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 |
| link:source-repository.html[Git]. Only some of the Apache developers |
| have write access to the Apache Logging repositories; everyone has |
| https://gitbox.apache.org/repos/asf?p=logging-log4j2.git[read |
| access]. |
| |
| [#issues] |
| == Issue Management |
| |
| The Log4j project uses the |
| https://issues.apache.org/JIRA/browse/LOG4J2[JIRA] bug tracking system |
| hosted and maintained by the Apache Software Foundation for tracking |
| bugs and enhancements. The project roadmap may be maintained in JIRA |
| through its RoadMap feature and through the use of Story or Epic issues. |
| |
| 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 JIRA 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. |
| |
| When appropriate, votes should be tallied in the JIRA issue. All votes |
| must be either sent to the mailing list or added directly to the JIRA |
| issue. |
| |
| [#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 JIRA in order to focus special |
| attention on the problem. An issue becomes a showstopper when it is |
| listed as such in JIRA 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 JIRA 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] |
| == changes.xml and Git logs |
| |
| Many code changes should be noted in the changes.xml file, and all |
| should be documented in Git commit messages. Often the text of the Git |
| log and the changes.xml 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] |
| === changes.xml |
| |
| changes.xml is the 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 changes.xml should include the appropriate JIRA issue |
| number 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. |