| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <!-- |
| 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. |
| --> |
| <!-- Generated by Apache Maven Doxia at 2015-05-10 --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| <title>Log4j – Project Guidelines - Apache Log4j 2</title> |
| <link rel="stylesheet" href="./css/bootstrap.min.css" type="text/css" /> |
| <link rel="stylesheet" href="./css/site.css" type="text/css" /> |
| <script type="text/javascript" src="./js/jquery.min.js"></script> |
| <script type="text/javascript" src="./js/bootstrap.min.js"></script> |
| <script type="text/javascript" src="./js/prettify.min.js"></script> |
| <script type="text/javascript" src="./js/site.js"></script> |
| <meta name="Date-Revision-yyyymmdd" content="20150510" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| |
| </head> |
| <body class="composite"> |
| <img class="logo-left" src="./images/ls-logo.jpg" alt="Apache logging services logo" /> |
| <img class="logo-right" src="./images/logo.jpg" alt="Apache log4j logo" /> |
| <div class="clear"></div> |
| |
| <div class="navbar"> |
| <div class="navbar-inner"> |
| <div class="container-fluid"> |
| <a class="brand" href="http://logging.apache.org/log4j/2.x/">Apache Log4j 2 ™</a> |
| <ul class="nav"> |
| <li> |
| |
| |
| <a href="http://wiki.apache.org/logging" class="external" target="_blank" title="Logging Wiki">Logging Wiki</a> |
| </li> |
| <li> |
| |
| |
| <a href="http://www.apache.org/" class="external" target="_blank" title="Apache">Apache</a> |
| </li> |
| <li> |
| <a href="../../" title="Logging Services">Logging Services</a> |
| </li> |
| <li> |
| |
| |
| <a href="https://analysis.apache.org/dashboard/index/org.apache.logging.log4j:log4j" class="external" target="_blank" title="Sonar">Sonar</a> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| |
| <div class="container-fluid"> |
| <table class="layout-table"> |
| <tr> |
| <td class="sidebar"> |
| <div class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-home"></i>Apache Log4j™ 2</li> |
| <li class="none"> |
| <a href="index.html" title="About">About</a> |
| </li> |
| <li class="none"> |
| <a href="download.html" title="Download">Download</a> |
| </li> |
| <li class="none"> |
| <a href="maven-artifacts.html" title="Maven and Ivy">Maven and Ivy</a> |
| </li> |
| <li class="none"> |
| <a href="build.html" title="Build">Build</a> |
| </li> |
| <li class="none active"> |
| <a href="guidelines.html" title="Guidelines">Guidelines</a> |
| </li> |
| <li class="none"> |
| <a href="javastyle.html" title="Style Guide">Style Guide</a> |
| </li> |
| <li class="none"> |
| <a href="changelog.html" title="Changelog">Changelog</a> |
| </li> |
| <li class="collapsed"> |
| <a href="javadoc.html" title="Javadoc">Javadoc</a> |
| </li> |
| <li class="none"> |
| <a href="runtime-dependencies.html" title="Runtime Dependencies">Runtime Dependencies</a> |
| </li> |
| <li class="none"> |
| <a href="faq.html" title="FAQ">FAQ</a> |
| </li> |
| <li class="none"> |
| <a href="articles.html" title="Articles">Articles</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-book"></i>Manual</li> |
| <li class="none"> |
| <a href="manual/index.html" title="Introduction">Introduction</a> |
| </li> |
| <li class="none"> |
| <a href="manual/architecture.html" title="Architecture">Architecture</a> |
| </li> |
| <li class="none"> |
| <a href="manual/migration.html" title="Log4j 1.x Migration">Log4j 1.x Migration</a> |
| </li> |
| <li class="collapsed"> |
| <a href="manual/api.html" title="API">API</a> |
| </li> |
| <li class="collapsed"> |
| <a href="manual/configuration.html" title="Configuration">Configuration</a> |
| </li> |
| <li class="collapsed"> |
| <a href="manual/webapp.html" title="Web Applications and JSPs">Web Applications and JSPs</a> |
| </li> |
| <li class="collapsed"> |
| <a href="manual/plugins.html" title="Plugins">Plugins</a> |
| </li> |
| <li class="collapsed"> |
| <a href="manual/lookups.html" title="Lookups">Lookups</a> |
| </li> |
| <li class="collapsed"> |
| <a href="manual/appenders.html" title="Appenders">Appenders</a> |
| </li> |
| <li class="collapsed"> |
| <a href="manual/layouts.html" title="Layouts">Layouts</a> |
| </li> |
| <li class="collapsed"> |
| <a href="manual/filters.html" title="Filters">Filters</a> |
| </li> |
| <li class="collapsed"> |
| <a href="manual/async.html" title="Async Loggers">Async Loggers</a> |
| </li> |
| <li class="none"> |
| <a href="manual/jmx.html" title="JMX">JMX</a> |
| </li> |
| <li class="none"> |
| <a href="manual/logsep.html" title="Logging Separation">Logging Separation</a> |
| </li> |
| <li class="collapsed"> |
| <a href="manual/extending.html" title="Extending Log4j">Extending Log4j</a> |
| </li> |
| <li class="collapsed"> |
| <a href="manual/customconfig.html" title="Extending Log4j Configuration">Extending Log4j Configuration</a> |
| </li> |
| <li class="collapsed"> |
| <a href="manual/customloglevels.html" title="Custom Log Levels">Custom Log Levels</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-cog"></i>Components</li> |
| <li class="none"> |
| <a href="log4j-api/index.html" title="API">API</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-core/index.html" title="Implementation">Implementation</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-jcl/index.html" title="Commons Logging Bridge">Commons Logging Bridge</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-1.2-api/index.html" title="Log4j 1.2 API">Log4j 1.2 API</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-slf4j-impl/index.html" title="SLF4J Binding">SLF4J Binding</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-jul/index.html" title="JUL Adapter">JUL Adapter</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-to-slf4j/index.html" title="Log4j 2 to SLF4J Adapter">Log4j 2 to SLF4J Adapter</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-flume-ng/index.html" title="Apache Flume Appender">Apache Flume Appender</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-taglib/index.html" title="Log4j Tag Library">Log4j Tag Library</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-jmx-gui/index.html" title="Log4j JMX GUI">Log4j JMX GUI</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-web/index.html" title="Log4j Web Application Support">Log4j Web Application Support</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-nosql/index.html" title="Log4j NoSQL support">Log4j NoSQL support</a> |
| </li> |
| <li class="none"> |
| <a href="log4j-iostreams/index.html" title="Log4j IO Streams">Log4j IO Streams</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-info-sign"></i>Project Information</li> |
| <li class="none"> |
| <a href="dependencies.html" title="Dependencies">Dependencies</a> |
| </li> |
| <li class="none"> |
| <a href="dependency-convergence.html" title="Dependency Convergence">Dependency Convergence</a> |
| </li> |
| <li class="none"> |
| <a href="dependency-management.html" title="Dependency Management">Dependency Management</a> |
| </li> |
| <li class="none"> |
| <a href="team-list.html" title="Project Team">Project Team</a> |
| </li> |
| <li class="none"> |
| <a href="mail-lists.html" title="Mailing Lists">Mailing Lists</a> |
| </li> |
| <li class="none"> |
| <a href="issue-tracking.html" title="Issue Tracking">Issue Tracking</a> |
| </li> |
| <li class="none"> |
| <a href="license.html" title="Project License">Project License</a> |
| </li> |
| <li class="none"> |
| <a href="source-repository.html" title="Source Repository">Source Repository</a> |
| </li> |
| <li class="none"> |
| <a href="project-summary.html" title="Project Summary">Project Summary</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-cog"></i>Project Reports</li> |
| <li class="none"> |
| <a href="changes-report.html" title="Changes Report">Changes Report</a> |
| </li> |
| <li class="none"> |
| <a href="jira-report.html" title="JIRA Report">JIRA Report</a> |
| </li> |
| <li class="none"> |
| <a href="surefire-report.html" title="Surefire Report">Surefire Report</a> |
| </li> |
| <li class="none"> |
| <a href="rat-report.html" title="RAT Report">RAT Report</a> |
| </li> |
| </ul> |
| </div> |
| <div id="poweredBy"> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> |
| <img class="poweredBy" alt="Built by Maven" src="./images/maven-feather.png" /> |
| </a> |
| </div> |
| </td> |
| <td class="content"> |
| <!-- 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. --> |
| |
| |
| <div class="section"> |
| <h2><a name="Apache_Log4j_Project_Guidelines"></a>Apache Log4j Project Guidelines</h2> |
| |
| |
| <p>This document defines the guidelines for the <a class="externalLink" 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"></a> |
| |
| <div class="section"> |
| <h3><a name="People_Places_and_Things"></a>People, Places, and Things</h3> |
| |
| <dl> |
| |
| <dt><b>Apache Logging Project Management Committee</b></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 ( <i>i.e.</i> , 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><b>Apache Logging Committers</b></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 ( <i>i.e.</i> , 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><b>Log4j Developers</b></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><b>mailing list</b></dt> |
| |
| <dd>The Log4j developers' primary mailing list for discussion of issues |
| and changes related to the project ( <i>log4j-dev@logging.apache.org</i> ). |
| Subscription to the list is open, but only subscribers can post |
| directly to the list.</dd> |
| |
| <dt><b>private list</b></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><b>Git</b></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 class="externalLink" href="https://git-wip-us.apache.org/repos/asf?p=logging-log4j2.git;a=summary">read access</a>.</dd> |
| </dl> |
| </div> |
| <a name="issues"></a> |
| |
| <div class="section"> |
| <h3><a name="Issue_Management"></a>Issue Management</h3> |
| |
| <p>The Log4j project uses the <a class="externalLink" 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 <b>must</b> 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> |
| </div> |
| <a name="voting"></a> |
| |
| <div class="section"> |
| <h3><a name="Voting"></a>Voting</h3> |
| |
| <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><b>+1</b></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><b>±0</b></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><b>-1</b></dt> |
| |
| <dd>No. On issues where consensus is required, this vote counts as a |
| <b>veto</b>. 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 <i>consensus approval</i> must receive at least <b>3 |
| binding +1</b> votes and <b>no vetoes</b>. An action item requiring <i>majority |
| approval</i> must receive at least <b>3 binding +1</b> votes and more <b>+1</b> |
| votes than <b>-1</b> votes ( <i>i.e.</i> , a majority with a minimum quorum of |
| three positive votes). All other action items are considered to have <i>lazy |
| approval</i> until someone votes <b>-1</b> , 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> |
| </div> |
| <a name="types-of-action-items"></a> |
| |
| <div class="section"> |
| <h3><a name="Types_of_Action_Items"></a>Types of Action Items</h3> |
| |
| <dl> |
| |
| <dt><b>Long Term Plans</b></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 <b>prior</b> to spending time on less adequate |
| solutions.</dd> |
| |
| <dt><b>Short Term Plans</b></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><b>Release Plan</b></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><b>Release Testing</b></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><b>Showstoppers/Blockers</b></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> |
| </div> |
| <a name="when-to-commit-a-change"></a> |
| |
| <div class="section"> |
| <h3><a name="When_to_Commit_a_Change"></a>When to Commit a Change</h3> |
| |
| <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> |
| </div> |
| <a name="changelogs"></a> |
| |
| <div class="section"> |
| <h3><a name="changes.xml_and_Git_logs"></a>changes.xml and Git logs</h3> |
| |
| <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> |
| </div> |
| <div class="section" id="subversion-log"> |
| <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> |
| |
| <div> |
| <pre> |
| 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></div> |
| </div> |
| <div class="section" id="changes"> |
| <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> |
| </div> |
| <a name="committing-security-fixes"></a> |
| |
| <div class="section"> |
| <h3><a name="Committing_Security_Fixes"></a>Committing Security Fixes</h3> |
| |
| <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> |
| </div> |
| <a name="patch"></a> |
| |
| <div class="section"> |
| <h3><a name="Patch_Format"></a>Patch Format</h3> |
| |
| <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 <tt>[PATCH]</tt> 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., |
| <tt>diff -u http_main.c.orig http_main.c >> patchfile.txt</tt> |
| or |
| <tt>svn diff http_main.c >> patchfile.txt</tt> |
| 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, |
| <tt>patch -s < patchfile</tt> |
| is issued in the target repository.</p> |
| </div> |
| <a name="teamwork"></a> |
| |
| <div class="section"> |
| <h3><a name="Teamwork"></a>Teamwork</h3> |
| |
| <p>Open source projects function best when everyone is aware of the "rules of the road" and abide by them.</p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <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> |
| </div> |
| </div> |
| |
| |
| </td> |
| </tr> |
| </table> |
| </div> |
| |
| <div class="footer"> |
| <p>Copyright © 1999-2015 <a class="external" href="http://www.apache.org">Apache Software Foundation</a>. All Rights Reserved.</p> |
| <p>Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p> |
| <p>Site powered by <a class="external" href="http://getbootstrap.com/">Twitter Bootstrap</a>. Icons from <a class="external" href="http://glyphicons.com/">Glyphicons Free</a>.</p> |
| </div> |
| </div> |
| </body> |
| </html> |
