| <?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>log4j-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 >> patchfile.txt</code> |
| or |
| <code>svn diff http_main.c >> 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 < 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> |