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 ( log4j-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.

Issue Management

The Log4j project uses the 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

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

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

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.

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.

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.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

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 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

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 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.