src/site/asciidoc/guidelines.adoc

////
    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://git-wip-us.apache.org/repos/asf?p=logging-log4j2.git;a=summary[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.