You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by ma...@apache.org on 2018/04/06 19:51:29 UTC
logging-log4j2 git commit: LOG4J2-1802: Convert guidelines page to
asciidoc
Repository: logging-log4j2
Updated Branches:
refs/heads/master dea6d414c -> ea311fe63
LOG4J2-1802: Convert guidelines page to asciidoc
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/ea311fe6
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/ea311fe6
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/ea311fe6
Branch: refs/heads/master
Commit: ea311fe638fa89a21255e00625642eea262a6f76
Parents: dea6d41
Author: Matt Sicker <bo...@gmail.com>
Authored: Fri Apr 6 14:50:58 2018 -0500
Committer: Matt Sicker <bo...@gmail.com>
Committed: Fri Apr 6 14:50:58 2018 -0500
----------------------------------------------------------------------
src/site/asciidoc/guidelines.adoc | 392 +++++++++++++++++++++++++++++++++
src/site/xdoc/guidelines.xml | 361 ------------------------------
2 files changed, 392 insertions(+), 361 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/ea311fe6/src/site/asciidoc/guidelines.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/guidelines.adoc b/src/site/asciidoc/guidelines.adoc
new file mode 100644
index 0000000..8f4dc72
--- /dev/null
+++ b/src/site/asciidoc/guidelines.adoc
@@ -0,0 +1,392 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ https://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+= Apache Log4j Project Guidelines
+
+This document defines the guidelines for the
+https://logging.apache.org/log4j/2.x[Apache Log4j Project]. It includes
+definitions of how conflict is resolved by voting, who is able to vote,
+the procedures to follow for proposing and making changes as well as
+guidelines for changing code.
+
+The objective here is to avoid unnecessary conflict over changes and
+continue to produce a quality system in a timely manner. Not all
+conflict can be avoided, but at least we can agree on the procedures for
+conflict to be resolved.
+
+[#people-places-and-things]
+== People, Places, and Things
+
+Apache Logging Project Management Committee::
+The group of volunteers who are responsible for managing the Apache
+Logging Projects, including Log4j. This includes deciding what is
+distributed as products of the Apache Logging Project, maintaining the
+Project's shared resources, speaking on behalf of the Project,
+resolving license disputes regarding Apache products, nominating new
+PMC members or committers, and establishing these guidelines.
++
+Membership in the Apache Logging PMC is by invitation only and must be
+approved by consensus of the active Logging PMC members. A PMC member is
+considered inactive by their own declaration or by not contributing in
+any form to the project for over six months. An inactive member can
+become active again by reversing whichever condition made them inactive
+( _i.e._ , by reversing their earlier declaration or by once again
+contributing toward the project's work). Membership can be revoked by a
+unanimous vote of all the active PMC members other than the member in
+question.
+
+Apache Logging Committers::
+The group of volunteers who are responsible for the technical aspects
+of the Apache Logging Projects. This group has write access to the
+appropriate source repositories and these volunteers may cast binding
+votes on any technical discussion. Although a committer usually joins
+due to their activity on one of the Logging projects, they will have
+commit access to all Logging projects.
++
+Membership as a Committer is by invitation only and must be approved by
+consensus of the active Logging PMC members. A Committer is considered
+inactive by their own declaration or by not contributing in any form to
+the project for over six months. An inactive member can become active
+again by reversing whichever condition made them inactive ( _i.e._ , by
+reversing their earlier declaration or by once again contributing toward
+the project's work). Membership can be revoked by a unanimous vote of
+all the active PMC members (except the member in question if they are a
+PMC member).
+
+Log4j Developers::
+All of the volunteers who are contributing time, code, documentation,
+or resources to the Log4j Project. A developer that makes sustained,
+welcome contributions to the project for over six months is usually
+invited to become a Committer, though the exact timing of such
+invitations depends on many factors.
+
+mailing list::
+The Log4j developers' primary mailing list for discussion of issues
+and changes related to the project ( _dev@logging.apache.org_ ).
+Subscription to the list is open, but only subscribers can post
+directly to the list.
+
+private list::
+The Logging PMC's private mailing list for discussion of issues that
+are inappropriate for public discussion, such as legal, personal, or
+security issues prior to a published fix. Subscription to the list is
+only open (actually: mandatory) to Apache Logging's Project Management
+Committee.
+
+Git::
+All of the Apache products are maintained in information repositories
+using either Subversion or Git; Log4j uses
+link:source-repository.html[Git]. Only some of the Apache developers
+have write access to the Apache Logging repositories; everyone has
+https://git-wip-us.apache.org/repos/asf?p=logging-log4j2.git;a=summary[read
+access].
+
+[#issues]
+== Issue Management
+
+The Log4j project uses the
+https://issues.apache.org/JIRA/browse/LOG4J2[JIRA] bug tracking system
+hosted and maintained by the Apache Software Foundation for tracking
+bugs and enhancements. The project roadmap may be maintained in JIRA
+through its RoadMap feature and through the use of Story or Epic issues.
+
+Many issues will be encountered by the project, each resulting in zero
+or more proposed action items. Issues should be raised on the mailing
+list as soon as they are identified. Action items *must* be raised on
+the mailing list and added to JIRA using the appropriate issue type. All
+action items may be voted on, but not all of them will require a formal
+vote.
+
+[#voting]
+== Voting
+
+Any of the Log4j Developers may vote on any issue or action item.
+However, the only binding votes are those cast by active members of the
+Apache Logging PMC; if the vote is about a change to source code or
+documentation, the primary author of what is being changed may also cast
+a binding vote on that issue. All other votes are non-binding. All
+developers are encouraged to participate in decisions, but the decision
+itself is made by those who have been long-time contributors to the
+project. In other words, the Apache Log4j Project is a minimum-threshold
+meritocracy.
+
+The act of voting carries certain obligations -- voting members are not
+only stating their opinion, they are agreeing to help do the work of the
+Log4j Project. Since we are all volunteers, members often become
+inactive for periods of time in order to take care of their "real jobs"
+or devote more time to other projects. It is therefore unlikely that the
+entire group membership will vote on every issue. To account for this,
+all voting decisions are based on a minimum quorum.
+
+Each vote can be made in one of three flavors:
+
++1::
+Yes, agree, or the action should be performed. On some issues, this
+vote is only binding if the voter has tested the action on their own
+system(s).
+±0::
+Abstain, no opinion, or I am happy to let the other group members
+decide this issue. An abstention may have detrimental effects if too
+many people abstain.
+-1::
+No. On issues where consensus is required, this vote counts as a
+*veto*. All vetoes must include an explanation of why the veto is
+appropriate. A veto with no explanation is void. No veto can be
+overruled. If you disagree with the veto, you should lobby the person
+who cast the veto. Voters intending to veto an action item should make
+their opinions known to the group immediately, so that the problem can
+be remedied as early as possible.
+
+An action item requiring _consensus approval_ must receive at least *3
+binding +1* votes and *no vetoes*. An action item requiring _majority
+approval_ must receive at least *3 binding +1* votes and more *+1* votes
+than *-1* votes ( _i.e._ , a majority with a minimum quorum of three
+positive votes). All other action items are considered to have _lazy
+approval_ until someone votes *-1* , after which point they are decided
+by either consensus or a majority vote, depending upon the type of
+action item.
+
+When appropriate, votes should be tallied in the JIRA issue. All votes
+must be either sent to the mailing list or added directly to the JIRA
+issue.
+
+[#types-of-action-items]
+== Types of Action Items
+
+Long Term Plans::
+Long term plans are simply announcements that group members are
+working on particular issues related to the Log4j software. These are
+not voted on, but group members who do not agree with a particular
+plan, or think an alternate plan would be better, are obligated to
+inform the group of their feelings. In general, it is always better to
+hear about alternate plans *prior* to spending time on less adequate
+solutions.
+Short Term Plans::
+Short term plans are announcements that a developer is working on a
+particular set of documentation or code files, with the implication
+that other developers should avoid them or try to coordinate their
+changes. This is a good way to proactively avoid conflict and possible
+duplication of work.
+Release Plan::
+A release plan is used to keep all the developers aware of when a
+release is desired, who will be the release manager, when the
+repository will be frozen in order to create the release, and assorted
+other trivia to keep us from tripping over ourselves during the final
+moments. Lazy majority (at least 3 x +1 and more +1 than -1) decides
+each issue in the release plan.
+Release Testing::
+After a new release is built it must be tested before being released
+to the public. Majority approval is required before the distribution
+can be publicly released.
+Showstoppers/Blockers::
+Showstoppers are issues that require a fix be in place before the next
+public release. They are listed in JIRA in order to focus special
+attention on the problem. An issue becomes a showstopper when it is
+listed as such in JIRA and remains so by lazy consensus.
+
+All product changes to the currently active repository are subject to
+lazy consensus. All product changes to a prior-branch (old version)
+repository require consensus before the change is committed.
+
+[#when-to-commit-a-change]
+== When to Commit a Change
+
+Ideas must be review-then-commit; patches can be commit-then-review.
+With a commit-then-review process, we trust that the developer doing the
+commit has a high degree of confidence in the change. Doubtful changes,
+new features, and large-scale overhauls need to be discussed before
+being committed to a repository. Any change that affects the semantics
+of arguments to configurable directives, significantly adds to the
+runtime size of the program, or changes the semantics of an existing API
+function must receive consensus approval on the mailing list before
+being committed.
+
+Each developer is responsible for notifying the mailing list and adding
+an action item to JIRA when they have an idea for a new feature or major
+change to propose for the product. The distributed nature of the Log4j
+project requires an advance notice of 48 hours in order to properly
+review a major change -- consensus approval of either the concept or a
+specific patch is required before the change can be committed. Note that
+a member might veto the concept (with an adequate explanation), but
+later rescind that veto if a specific patch satisfies their objections.
+No advance notice is required to commit singular bug fixes.
+
+Related changes should be committed as a group, or very closely
+together. Half-completed projects should not be committed unless doing
+so is necessary to pass the baton to another developer who has agreed to
+complete the project in short order. All code changes must be
+successfully compiled and unit tests pass on the developer's platform
+before being committed.
+
+The current source code tree should be capable of complete compilation
+at all times. However, it is sometimes impossible for a developer on one
+platform to avoid breaking some other platform when a change is
+committed, particularly when completing the change requires access to a
+special development tool on that other platform. If it is anticipated
+that a given change will break some other platform, the committer must
+indicate that in the commit log.
+
+The committer is responsible for the quality of any third-party code or
+documentation they commit to the repository. All software committed to
+the repository must be covered by the Apache LICENSE or contain a
+copyright and license that allows redistribution under the same
+conditions as the Apache LICENSE.
+
+A committed change must be reversed if it is vetoed by one of the voting
+members and the veto conditions cannot be immediately satisfied by the
+equivalent of a "bug fix" commit. The veto must be rescinded before the
+change can be included in any public release.
+
+[#changelogs]
+== changes.xml and Git logs
+
+Many code changes should be noted in the changes.xml file, and all
+should be documented in Git commit messages. Often the text of the Git
+log and the changes.xml entry are the same, but the distinct
+requirements sometimes result in different information.
+
+[#subversion-log]
+=== Git log
+
+The Git commit log message contains any information needed by
+
+* fellow developers or other people researching source code
+changes/fixes
+* end users (at least point out what the implications are for end users;
+it doesn't have to be in the most user friendly wording)
+
+If the code change was provided by a non-committer, attribute it using
+Submitted-by. If the change was committed verbatim, identify the
+committer(s) who reviewed it with Reviewed-by. If the change was
+committed with modifications, use the appropriate wording to document
+that, perhaps "committed with changes" if the person making the commit
+made the changes, or "committed with contributions from xxxx" if others
+made contributions to the code committed.
+
+Example log message:
+
+....
+LOG4J2-9999
+Check the return code from parsing the content length, to avoid a
+crash if requests contain an invalid content length.
+Submitted by: Jane Doe <janedoe example.com>
+Reviewed by: susiecommitter
+....
+
+[#changes]
+=== changes.xml
+
+changes.xml is the subset of the information that end users need to see
+when they upgrade from one release to the next:
+
+* what can I now do that I couldn't do before
+* what problems that we anticipate a user could have suffered from are
+now fixed
+* all security fixes included, with CVE number. (If not available at the
+time of the commit, add later.)
+
+All entries in changes.xml should include the appropriate JIRA issue
+number and should credit contributions made by non-committers by
+referencing them in the due-to attribute even if modifications needed to
+be made to the contribution.
+
+The attribution for the change is anyone responsible for the code
+changes.
+
+[#committing-security-fixes]
+== Committing Security Fixes
+
+Open source projects, ASF or otherwise, have varying procedures for
+commits of vulnerability fixes. One important aspect of these procedures
+is whether or not fixes to vulnerabilities can be committed to a
+repository with commit logs and possibly CHANGES entries which
+purposefully obscure the vulnerability and omit any available
+vulnerability tracking information. The Apache HTTP Server project has
+decided that it is in the best interest of our users that the initial
+commit of such code changes to any branch will provide the best
+description available at that time as well as any available tracking
+information such as CVE number. Committing of the fix will be delayed
+until the project determines that all of the information about the issue
+can be shared.
+
+In some cases there are very real benefits to sharing code early even if
+full information about the issue cannot, including the potential for
+broader review, testing, and distribution of the fix. This is outweighed
+by the concern that sharing only the code changes allows skilled
+analysts to determine the impact and exploit mechanisms but does not
+allow the general user community to determine if preventative measures
+should be taken.
+
+If a vulnerability is partially disclosed by committing a fix before the
+bug is determined to be exploitable, the httpd security team will decide
+on a case by case basis when to document the security implications and
+tracking number.
+
+[#patch]
+== Patch Format
+
+When a specific change to the software is proposed for discussion or
+voting on the mailing list, it should be presented in the form of input
+to the patch command. When sent to the mailing list, the message should
+contain a Subject beginning with `[PATCH]` and a distinctive one-line
+summary corresponding to the action item for that patch. Afterwords, the
+patch summary in the STATUS file should be updated to point to the
+Message-ID of that message.
+
+The patch should be created by using the diff -u command from the
+original software file(s) to the modified software file(s). E.g.,
+`diff -u http_main.c.orig http_main.c >> patchfile.txt` or
+`svn diff http_main.c >> patchfile.txt` All patches necessary to address
+an action item should be concatenated within a single patch message. If
+later modification of the patch proves necessary, the entire new patch
+should be posted and not just the difference between two patches. The
+STATUS file entry should then be updated to point to the new patch
+message.
+
+The completed patchfile should produce no errors or prompts when the
+command, `patch -s < patchfile` is issued in the target repository.
+
+[#teamwork]
+== Teamwork
+
+Open source projects function best when everyone is aware of the "rules
+of the road" and abide by them.
+
+1. Error on the side of caution. If you don’t understand it, don’t
+touch it and ask on the list. If you think you understand it read it
+again or ask until you are sure you do. Nobody will blame you for asking
+questions.
+2. Don’t break the build - if there is the slightest chance the change
+you are making could cause unit test failures, run all unit tests.
+Better yet, get in the habit of always running the unit tests before
+doing the commit.
+3. If the build breaks and you have made recent changes then assume you
+broke it and try to fix it. Although it might not have been something
+you did it will make others feel a lot better than having to fix the
+mistake for you. Everyone makes mistakes. Taking responsibility for them
+is a good thing.
+4. Don’t change things to match your personal preference - the project
+has link:javastyle.html[style guidelines] that are validated with
+checkstyle, PMD, and other tools. If you aren't fixing a bug, fixing a
+problem identified by the tools, or fixing something specifically called
+out in these guidelines then start a discussion to see if the change is
+something the project wants before starting to work on it. We try to
+discuss things first and then implement the consensus reached in the
+discussion.
+5. Along the same lines, do not commit automatic changes made by your
+IDE without reviewing them. There are a few places in the code that
+cannot conform to style guidelines without causing errors in some
+environments. These are clearly marked and must be left as is.
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/ea311fe6/src/site/xdoc/guidelines.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/guidelines.xml b/src/site/xdoc/guidelines.xml
deleted file mode 100644
index 3c18861..0000000
--- a/src/site/xdoc/guidelines.xml
+++ /dev/null
@@ -1,361 +0,0 @@
-<?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 >> 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>