<?xml version="1.0" encoding="UTF-8"?>
<!--
 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.
-->
<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">

  <properties>
    <title>Project Guidelines</title>
  </properties>

  <body>
    <section name="Apache Log4j Project Guidelines">

      <p>This document defines the guidelines for the <a href="http://logging.apache.org/log4j/2.x">Apache Log4j
        Project</a>. 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.</p>
      <p>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.</p>
      <a name="people-places-and-things"/>
      <subsection name="People, Places, and Things">
      <dl>
        <dt><strong>Apache Logging Project Management Committee</strong></dt>
        <dd>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.</dd>
      </dl>
      <p>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 ( <em>i.e.</em> , 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.</p>
      <dl>
        <dt><strong>Apache Logging Committers</strong></dt>
        <dd>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.</dd>
      </dl>
      <p>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 ( <em>i.e.</em> , 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).</p>
      <dl>
        <dt><strong>Log4j Developers</strong></dt>
        <dd>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.</dd>
        <dt><strong>mailing list</strong></dt>
        <dd>The Log4j developers' primary mailing list for discussion of issues
          and changes related to the project ( <em>dev@logging.apache.org</em> ).
          Subscription to the list is open, but only subscribers can post
          directly to the list.</dd>
        <dt><strong>private list</strong></dt>
        <dd>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.</dd>
        <dt><strong>Git</strong></dt>
        <dd>All of the Apache products are maintained in information
          repositories using either Subversion or Git; Log4j uses <a href="source-repository.html">Git</a>. Only some of the
          Apache developers have write access to the Apache Logging repositories; everyone
          has <a href="https://git-wip-us.apache.org/repos/asf?p=logging-log4j2.git;a=summary">read access</a>.</dd>
      </dl>
      </subsection>
      <a name="issues"/>
      <subsection name="Issue Management">
      <p>The Log4j project uses the <a href="https://issues.apache.org/jira/browse/LOG4J2">Jira</a> 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.</p>
      <p>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 <strong>must</strong> 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.</p>
      </subsection>
      <a name="voting"/>
      <subsection name="Voting">
      <p>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.</p>
      <p>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.</p>
      <p>Each vote can be made in one of three flavors:</p>
      <dl>
        <dt><strong>+1</strong></dt>
        <dd>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).</dd>
        <dt><strong>±0</strong></dt>
        <dd>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.</dd>
        <dt><strong>-1</strong></dt>
        <dd>No. On issues where consensus is required, this vote counts as a
          <strong>veto</strong>. 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.</dd>
      </dl>
      <p>An action item requiring <em>consensus approval</em> must receive at least <strong>3
        binding +1</strong> votes and <strong>no vetoes</strong>. An action item requiring <em>majority
        approval</em> must receive at least <strong>3 binding +1</strong> votes and more <strong>+1</strong>
        votes than <strong>-1</strong> votes ( <em>i.e.</em> , a majority with a minimum quorum of
        three positive votes). All other action items are considered to have <em>lazy
          approval</em> until someone votes <strong>-1</strong> , after which point they are decided
        by either consensus or a majority vote, depending upon the type of action
        item.</p>
      <p>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.</p>
      </subsection>
      <a name="types-of-action-items"/>
      <subsection name="Types of Action Items">
      <dl>
        <dt><strong>Long Term Plans</strong></dt>
        <dd>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 <strong>prior</strong> to spending time on less adequate
          solutions.</dd>
        <dt><strong>Short Term Plans</strong></dt>
        <dd>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.</dd>
        <dt><strong>Release Plan</strong></dt>
        <dd>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.</dd>
        <dt><strong>Release Testing</strong></dt>
        <dd>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.</dd>
        <dt><strong>Showstoppers/Blockers</strong></dt>
        <dd>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.</dd>
      </dl>
      <p>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.</p>
      </subsection>
      <a name="when-to-commit-a-change"/>
      <subsection name="When to Commit a Change">
      <p>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.</p>
      <p>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.</p>
      <p>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.</p>
      <p>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.</p>
      <p>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.</p>
      <p>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.</p>
      </subsection>
      <a name="changelogs"/>
      <subsection name="changes.xml and Git logs">
      <p>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.</p>
      <h3 id="subversion-log">Git log</h3>
      <p>The Git commit log message contains any information needed by</p>
      <ul>
        <li>
          <p>fellow developers or other people researching source code changes/fixes</p>
        </li>
        <li>
          <p>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)</p>
        </li>
      </ul>
      <p>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.</p>
      <p>Example log message:</p>
        <pre><![CDATA[
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
        ]]></pre>
      <h3 id="changes">changes.xml</h3>
      <p>changes.xml is the subset of the information that end users need to see when
        they upgrade from one release to the next:</p>
      <ul>
        <li>
          <p>what can I now do that I couldn't do before</p>
        </li>
        <li>
          <p>what problems that we anticipate a user could have suffered from are now
            fixed</p>
        </li>
        <li>
          <p>all security fixes included, with CVE number. (If not available at the
            time of the commit, add later.)</p>
        </li>
      </ul>
      <p>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.</p>
      <p>The attribution for the change is anyone responsible for the code changes.</p>
      </subsection>
      <a name="committing-security-fixes"/>
      <subsection name="Committing Security Fixes">
      <p>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.</p>
      <p>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.</p>
      <p>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.</p>
      </subsection>
      <a name="patch"/>
      <subsection name="Patch Format">
      <p>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 <code>[PATCH]</code> 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.</p>
      <p>The patch should be created by using the <kbd>diff -u</kbd> command from
        the original software file(s) to the modified software file(s). E.g.,
        <code>diff -u http_main.c.orig http_main.c &gt;&gt; patchfile.txt</code>
        or
        <code>svn diff http_main.c &gt;&gt; patchfile.txt</code>
        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.</p>
      <p>The completed patchfile should produce no errors or prompts when the
        command,
        <code>patch -s &lt; patchfile</code>
        is issued in the target repository.</p>
      </subsection>
      <a name="teamwork"/>
      <subsection name="Teamwork">
        <p>Open source projects function best when everyone is aware of the "rules of the road" and abide by them.</p>
        <ol>
          <li>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.</li>
          <li>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.</li>
          <li>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.</li>
          <li>Don’t change things to match your personal preference - the project has <a href="javastyle.html">style guidelines</a>
            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.</li>
          <li>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.</li>
        </ol>
      </subsection>
    </section>
  </body>
</document>
