| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.9.1 from src/site/xdoc/guidelines.xml at 2019-12-11 |
| | Rendered using Apache Maven Fluido Skin 1.8 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1" /> |
| <meta name="generator" content="Apache Maven Doxia Site Renderer 1.9.1" /> |
| <title>Log4j – Project Guidelines</title> |
| <link rel="stylesheet" href="./css/apache-maven-fluido-1.8.min.css" /> |
| <link rel="stylesheet" href="./css/site.css" /> |
| <link rel="stylesheet" href="./css/print.css" media="print" /> |
| <script src="./js/apache-maven-fluido-1.8.min.js"></script> |
| </head> |
| <body class="topBarDisabled"> |
| <div class="container-fluid"> |
| <header> |
| <div id="banner"> |
| <div class="pull-left"><a href="http://logging.apache.org" id="bannerLeft"><img src="images/ls-logo.jpg" alt=""/></a></div> |
| <div class="pull-right"><a href="http://logging.apache.org/log4j/2.x" id="bannerRight"><img src="images/logo.png" alt=""/></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 2019-12-11<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 2.13.0</li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://github.com/apache/logging-log4j2" class="externalLink" title="GitHub">GitHub</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://analysis.apache.org/dashboard/index/org.apache.logging.log4j:log4j" class="externalLink" title="Sonar">Sonar</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="../../" title="Logging Services">Logging Services</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://www.apache.org/" class="externalLink" title="Apache">Apache</a></li> |
| <li class="pull-right"><a href="https://cwiki.apache.org/confluence/display/LOGGING/Log4j" class="externalLink" title="Logging Wiki">Logging Wiki</a></li> |
| </ul> |
| </div> |
| </header> |
| <div class="row-fluid"> |
| <header id="leftColumn" class="span2"> |
| <nav class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/home.png" alt="Apache Log4j™ 2" border="0"/> Apache Log4j™ 2</li> |
| <li><a href="index.html" title="About"><span class="none"></span>About</a></li> |
| <li><a href="download.html" title="Download"><span class="none"></span>Download</a></li> |
| <li><a href="javadoc.html" title="Javadoc"><span class="icon-chevron-right"></span>Javadoc</a></li> |
| <li><a href="maven-artifacts.html" title="Maven, Ivy, Gradle Artifacts"><span class="icon-chevron-right"></span>Maven, Ivy, Gradle Artifacts</a></li> |
| <li><a href="runtime-dependencies.html" title="Runtime Dependencies"><span class="none"></span>Runtime Dependencies</a></li> |
| <li><a href="changelog.html" title="Changelog"><span class="none"></span>Changelog</a></li> |
| <li><a href="faq.html" title="FAQ"><span class="none"></span>FAQ</a></li> |
| <li><a href="performance.html" title="Performance"><span class="icon-chevron-right"></span>Performance</a></li> |
| <li><a href="articles.html" title="Articles and Tutorials"><span class="none"></span>Articles and Tutorials</a></li> |
| <li><a href="thanks.html" title="Thanks"><span class="none"></span>Thanks</a></li> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/pencil.png" alt="For Contributors" border="0"/> For Contributors</li> |
| <li><a href="build.html" title="Building Log4j from Source"><span class="none"></span>Building Log4j from Source</a></li> |
| <li class="active"><a href="#"><span class="none"></span>Guidelines</a></li> |
| <li><a href="javastyle.html" title="Style Guide"><span class="none"></span>Style Guide</a></li> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/book.png" alt="Manual" border="0"/> Manual</li> |
| <li><a href="manual/index.html" title="Introduction"><span class="none"></span>Introduction</a></li> |
| <li><a href="manual/architecture.html" title="Architecture"><span class="none"></span>Architecture</a></li> |
| <li><a href="manual/compatibility.html" title="Log4j 1.x Compatibility"><span class="none"></span>Log4j 1.x Compatibility</a></li> |
| <li><a href="manual/migration.html" title="Log4j 1.x Migration"><span class="none"></span>Log4j 1.x Migration</a></li> |
| <li><a href="manual/api.html" title="Java API"><span class="icon-chevron-right"></span>Java API</a></li> |
| <li><a href="manual/scala-api.html" title="Scala API"><span class="none"></span>Scala API</a></li> |
| <li><a href="manual/configuration.html" title="Configuration"><span class="icon-chevron-right"></span>Configuration</a></li> |
| <li><a href="manual/usage.html" title="Usage"><span class="icon-chevron-right"></span>Usage</a></li> |
| <li><a href="manual/webapp.html" title="Web Applications and JSPs"><span class="icon-chevron-right"></span>Web Applications and JSPs</a></li> |
| <li><a href="manual/lookups.html" title="Lookups"><span class="icon-chevron-right"></span>Lookups</a></li> |
| <li><a href="manual/appenders.html" title="Appenders"><span class="icon-chevron-right"></span>Appenders</a></li> |
| <li><a href="manual/layouts.html" title="Layouts"><span class="icon-chevron-right"></span>Layouts</a></li> |
| <li><a href="manual/filters.html" title="Filters"><span class="icon-chevron-right"></span>Filters</a></li> |
| <li><a href="manual/async.html" title="Async Loggers"><span class="icon-chevron-right"></span>Async Loggers</a></li> |
| <li><a href="manual/garbagefree.html" title="Garbage-free Logging"><span class="icon-chevron-right"></span>Garbage-free Logging</a></li> |
| <li><a href="manual/jmx.html" title="JMX"><span class="none"></span>JMX</a></li> |
| <li><a href="manual/logsep.html" title="Logging Separation"><span class="none"></span>Logging Separation</a></li> |
| <li><a href="manual/extending.html" title="Extending Log4j"><span class="icon-chevron-right"></span>Extending Log4j</a></li> |
| <li><a href="manual/plugins.html" title="Plugins"><span class="icon-chevron-right"></span>Plugins</a></li> |
| <li><a href="manual/customconfig.html" title="Programmatic Log4j Configuration"><span class="icon-chevron-right"></span>Programmatic Log4j Configuration</a></li> |
| <li><a href="manual/customloglevels.html" title="Custom Log Levels"><span class="icon-chevron-right"></span>Custom Log Levels</a></li> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/tag.png" alt="Related Projects" border="0"/> Related Projects</li> |
| <li><a href="http://logging.apache.org/log4j/scala/index.html" class="externalLink" title="Log4j-Scala"><span class="none"></span>Log4j-Scala</a></li> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/link.png" alt="Legacy Sites" border="0"/> Legacy Sites</li> |
| <li><a href="http://logging.apache.org/log4j/1.2/" class="externalLink" title="Log4j 1.2 - End of Life"><span class="none"></span>Log4j 1.2 - End of Life</a></li> |
| <li><a href="http://logging.apache.org/log4j/log4j-2.3/" class="externalLink" title="Log4j 2.3 - Java 6"><span class="none"></span>Log4j 2.3 - Java 6</a></li> |
| <li><a href="http://logging.apache.org/log4j/log4j-2.12.1" class="externalLink" title="Log4j 2.12.1 - Java 7"><span class="none"></span>Log4j 2.12.1 - Java 7</a></li> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/cog.png" alt="Components" border="0"/> Components</li> |
| <li><a href="log4j-api/index.html" title="API"><span class="none"></span>API</a></li> |
| <li><a href="log4j-core/index.html" title="Implementation"><span class="none"></span>Implementation</a></li> |
| <li><a href="log4j-jcl/index.html" title="Commons Logging Bridge"><span class="none"></span>Commons Logging Bridge</a></li> |
| <li><a href="log4j-1.2-api/index.html" title="Log4j 1.2 API"><span class="none"></span>Log4j 1.2 API</a></li> |
| <li><a href="log4j-slf4j-impl/index.html" title="SLF4J Binding"><span class="none"></span>SLF4J Binding</a></li> |
| <li><a href="log4j-jul/index.html" title="JUL Adapter"><span class="none"></span>JUL Adapter</a></li> |
| <li><a href="log4j-to-slf4j/index.html" title="Log4j 2 to SLF4J Adapter"><span class="none"></span>Log4j 2 to SLF4J Adapter</a></li> |
| <li><a href="log4j-flume-ng/index.html" title="Apache Flume Appender"><span class="none"></span>Apache Flume Appender</a></li> |
| <li><a href="log4j-taglib/index.html" title="Log4j Tag Library"><span class="none"></span>Log4j Tag Library</a></li> |
| <li><a href="log4j-jmx-gui/index.html" title="Log4j JMX GUI"><span class="none"></span>Log4j JMX GUI</a></li> |
| <li><a href="log4j-web/index.html" title="Log4j Web Application Support"><span class="none"></span>Log4j Web Application Support</a></li> |
| <li><a href="log4j-appserver/index.html" title="Log4j Application Server Integration"><span class="none"></span>Log4j Application Server Integration</a></li> |
| <li><a href="log4j-couchdb/index.html" title="Log4j CouchDB appender"><span class="none"></span>Log4j CouchDB appender</a></li> |
| <li><a href="log4j-mongodb2/index.html" title="Log4j MongoDB2 appender"><span class="none"></span>Log4j MongoDB2 appender</a></li> |
| <li><a href="log4j-mongodb3/index.html" title="Log4j MongoDB3 appender"><span class="none"></span>Log4j MongoDB3 appender</a></li> |
| <li><a href="log4j-cassandra/index.html" title="Log4j Cassandra appender"><span class="none"></span>Log4j Cassandra appender</a></li> |
| <li><a href="log4j-iostreams/index.html" title="Log4j IO Streams"><span class="none"></span>Log4j IO Streams</a></li> |
| <li><a href="log4j-liquibase/index.html" title="Log4j Liquibase Binding"><span class="none"></span>Log4j Liquibase Binding</a></li> |
| <li><a href="log4j-docker/index.html" title="Log4j Docker Support"><span class="none"></span>Log4j Docker Support</a></li> |
| <li><a href="log4j-spring-cloud-config/log4j-spring-cloud-config-client/index.html" title="Log4j Spring Cloud Config Client"><span class="none"></span>Log4j Spring Cloud Config Client</a></li> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/info.png" alt="Project Information" border="0"/> Project Information</li> |
| <li><a href="dependency-convergence.html" title="Dependency Convergence"><span class="none"></span>Dependency Convergence</a></li> |
| <li><a href="dependency-management.html" title="Dependency Management"><span class="none"></span>Dependency Management</a></li> |
| <li><a href="team-list.html" title="Project Team"><span class="none"></span>Project Team</a></li> |
| <li><a href="mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a></li> |
| <li><a href="issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a></li> |
| <li><a href="license.html" title="Project License"><span class="none"></span>Project License</a></li> |
| <li><a href="source-repository.html" title="Source Repository"><span class="none"></span>Source Repository</a></li> |
| <li><a href="project-summary.html" title="Project Summary"><span class="none"></span>Project Summary</a></li> |
| <li class="nav-header"><img class="imageLink" src="img/glyphicons/layers.png" alt="Project Reports" border="0"/> Project Reports</li> |
| <li><a href="changes-report.html" title="Changes Report"><span class="none"></span>Changes Report</a></li> |
| <li><a href="jira-report.html" title="JIRA Report"><span class="none"></span>JIRA Report</a></li> |
| <li><a href="rat-report.html" title="RAT Report"><span class="none"></span>RAT Report</a></li> |
| </ul> |
| </nav> |
| <div class="well sidebar-nav"> |
| <hr /> |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /></a> |
| </div> |
| </div> |
| </header> |
| <main id="bodyColumn" class="span10" > |
| |
| |
| |
| <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> |
| <section> |
| <h3><a name="People.2C_Places.2C_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>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> |
| </section> |
| <a name="issues"></a> |
| <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> |
| </section> |
| <a name="voting"></a> |
| <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> |
| </section> |
| <a name="types-of-action-items"></a> |
| <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> |
| </section> |
| <a name="when-to-commit-a-change"></a> |
| <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> |
| </section> |
| <a name="changelogs"></a> |
| <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> |
| </section><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> |
| </section><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> |
| </section> |
| <a name="committing-security-fixes"></a> |
| <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> |
| </section> |
| <a name="patch"></a> |
| <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 [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.</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., |
| 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.</p> |
| |
| <p>The completed patchfile should produce no errors or prompts when the |
| command, |
| patch -s < patchfile |
| is issued in the target repository.</p> |
| </section> |
| <a name="teamwork"></a> |
| <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> |
| </section> |
| </section> |
| |
| |
| </main> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p align="center">Copyright © 1999-2019 <a class="external" href="http://www.apache.org">The Apache Software Foundation</a>. All Rights Reserved.<br> |
| Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p> |
| </div> |
| </div> |
| </footer> |
| </body> |
| </html> |