You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by jo...@apache.org on 2012/05/07 00:53:20 UTC
svn commit: r1334814 [3/3] - /httpd/site/trunk/content/dev/
Copied: httpd/site/trunk/content/dev/patches.mdtext (from r1334802, httpd/site/trunk/content/dev/patches.xml)
URL: http://svn.apache.org/viewvc/httpd/site/trunk/content/dev/patches.mdtext?p2=httpd/site/trunk/content/dev/patches.mdtext&p1=httpd/site/trunk/content/dev/patches.xml&r1=1334802&r2=1334814&rev=1334814&view=diff
==============================================================================
--- httpd/site/trunk/content/dev/patches.xml (original)
+++ httpd/site/trunk/content/dev/patches.mdtext Sun May 6 22:53:19 2012
@@ -1,205 +1,176 @@
-<?xml version="1.0"?>
-<document>
- <properties>
- <author email="docs@httpd.apache.org">Documentation Group</author>
- <title>How to Contribute Patches to Apache</title>
- </properties>
-<body>
-
-<section>
-<title>How to Contribute Patches to Apache</title>
-
-<p>Third-party patches are essential to the success of Apache -
-the "core" developers don't have access to all platforms, and
-we certainly aren't using Apache in all the different ways it
-can be used. To that end, we try to make it as easy as possible
-to contribute code. However, we do have some expectations of
-contributors, and a process to all this, simply to help us
-manage the flood of contributions we could get. This page
-describes that process.</p>
-
-</section>
-
-<section>
-<title>Code Style</title>
-
-<p>We have a fairly firmly-set code format we use in our code; it was
-one we arrived at through no small amount of debate. The format is
-described in our official <a href="styleguide.html">style guide</a>.
-While there is some code in the project that does not follow the style
-guide, it is generally safe to assume that your code is wrong if it
-is not formatted like the other code in the file.</p>
-
-<p>We also have very high expectations for code quality; and to us this
-means the avoidance of excessive static buffers, using the
-memory pool mechanism (which ensures proper cleanup), and otherwise
-writing thread-safe code. We also expect one or two levels of
-optimizations to be applied, too - is a bitmask faster for this? Is
-a strchr() faster than an index()? Etc. Of course it'd be nice if we
-had a real document describing this all, but we don't yet.</p>
-</section>
-
-<section>
-<title>Documentation</title>
-
-<p>The Apache documentation needs to be updated for some patches,
-most often for enhancements. You may wish to see if your patch
-is considered generally acceptable before updating the documentation.
-Patches for the documentation are submitted with any code changes in
-the same patch format.</p>
-
-<p>Please note that for Apache 2.0 and above, most of the
-documentation is generated from XML. Your changes need to be made to
-the XML version. See
-<a href="http://httpd.apache.org/docs-project/docsformat.html">
-http://httpd.apache.org/docs-project/docsformat.html</a> for more
-information.</p>
-
-</section>
-
-<section>
-<title>Choosing a level of Apache code for comparison</title>
-
-<p>Currently, there are three active Apache httpd source trees:</p>
-<ol>
- <li>Apache httpd 2.0.x (legacy/maintenance)</li>
- <li>Apache httpd 2.2.x (previous release)</li>
- <li>Apache httpd 2.4.x (current release, GA)</li>
- <li>Apache httpd 2.5.x (development/beta version)</li>
-</ol>
-
-<p>A patch should be created against the last public release or, if
-practical, the latest code in subversion for the relevant source tree.
-Patches created against older releases may not apply to current
-sources.</p>
-
-<p>Instructions for obtaining a source tree from subversion are at
- <a href="http://httpd.apache.org/dev/devnotes.html">
- Apache Development Notes</a>
-</p>.
+Title: How to Contribute Patches to Apache
+Notice: 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.
+
+Third-party patches are essential to the success of Apache - the "core"
+developers don't have access to all platforms, and we certainly aren't
+using Apache in all the different ways it can be used. To that end, we try
+to make it as easy as possible to contribute code. However, we do have some
+expectations of contributors, and a process to all this, simply to help us
+manage the flood of contributions we could get. This page describes that
+process.
+
+# Code Style #
+
+We have a fairly firmly-set code format we use in our code; it was one we
+arrived at through no small amount of debate. The format is described in
+our official [style guide](styleguide.html). While there is some code in
+the project that does not follow the style guide, it is generally safe to
+assume that your code is wrong if it is not formatted like the other code
+in the file.
+
+We also have very high expectations for code quality; and to us this means
+the avoidance of excessive static buffers, using the memory pool mechanism
+(which ensures proper cleanup), and otherwise writing thread-safe code. We
+also expect one or two levels of optimizations to be applied, too - is a
+bitmask faster for this? Is a strchr() faster than an index()? Etc. Of
+course it'd be nice if we had a real document describing this all, but we
+don't yet.
+
+# Documentation #
+
+The Apache documentation needs to be updated for some patches, most often
+for enhancements. You may wish to see if your patch is considered generally
+acceptable before updating the documentation. Patches for the documentation
+are submitted with any code changes in the same patch format.
+
+Please note that for Apache 2.0 and above, most of the documentation is
+generated from XML. Your changes need to be made to the XML version. See
+[http://httpd.apache.org/docs-project/docsformat.html](http://httpd.apache.org/docs-project/docsformat.html)
+for more information.
+
+# Choosing a level of Apache code for comparison #
+
+Currently, there are three active Apache httpd source trees:
+
+1. Apache httpd 2.0.x (legacy/maintenance)
+
+1. Apache httpd 2.2.x (previous release)
+
+1. Apache httpd 2.4.x (current release, GA)
+
+1. Apache httpd 2.5.x (development/beta version)
+
+A patch should be created against the last public release or, if practical,
+the latest code in subversion for the relevant source tree. Patches created
+against older releases may not apply to current sources.
-</section>
+Instructions for obtaining a source tree from subversion are at [Apache
+Development Notes](http://httpd.apache.org/dev/devnotes.html)
-<section>
-<title>Patch Format</title>
-
-<p>We prefer that patches be submitted in unified diff format:</p>
+# Patch Format #
+We prefer that patches be submitted in unified diff format:
<BLOCKQUOTE><CODE>diff -u file-old.c file.c</CODE></BLOCKQUOTE>
+but that isn't available on all platforms. If your platform doesn't support
+unified diffs, please use a context diff instead:
+<BLOCKQUOTE><CODE>diff -C3 file-old.c file.c</CODE></BLOCKQUOTE>
+where<CODE>file.c</CODE>is the file affected. We should be able to feed the
+patch directly into the "patch" program and have it update the file or set
+of files. The `-C3` is very important - line numbers can change on a daily
+basis in some code files, so having context is crucial to knowing where it
+all really goes.
-<p>but that isn't available on all platforms. If your platform doesn't
-support unified diffs, please use a context diff instead:</p>
+If multiple files are modified, the following setup can simplify the
+management of original and modified files:
-<BLOCKQUOTE><CODE>diff -C3 file-old.c file.c</CODE></BLOCKQUOTE>
+1. <BLOCKQUOTE><CODE>cd /sources</CODE></BLOCKQUOTE>
-<p>where <CODE>file.c</CODE> is the file affected. We should be
-able to feed the patch directly into the "patch" program and have it
-update the file or set of files. The <code>-C3</code> is very
-important - line numbers can change on a daily basis in some code
-files, so having context is crucial to knowing where it all really
-goes.</p>
-
-<p>If multiple files are modified, the following setup can simplify
-the management of original and modified files:</p>
-
-<ol>
- <li><BLOCKQUOTE><CODE>cd /sources</CODE></BLOCKQUOTE></li>
- <li><BLOCKQUOTE><CODE>tar xvzf httpd-2.0.x.tar.gz</CODE></BLOCKQUOTE></li>
- <li><BLOCKQUOTE><CODE>cp -ax httpd-2.0.x httpd-2.0.x.new</CODE></BLOCKQUOTE></li>
- <li>edit files in httpd-2.0.x.new and build/test</li>
- <li><BLOCKQUOTE><CODE>cd /sources</CODE></BLOCKQUOTE></li>
- <li><BLOCKQUOTE><CODE>diff -ru httpd-2.0.x httpd-2.0.x.new >my.unified.diff.patch</CODE></BLOCKQUOTE></li>
-</ol>
-
-<p>If your source tree was checked out of subversion,
-<BLOCKQUOTE><CODE>svn diff</CODE></BLOCKQUOTE> will create the
-patch in the correct format.</p>
-
-</section>
-
-<section>
-<title>Submitting your Patch</title>
-
-<p>Traditionally, patches have been submitted on the developer's
-mailing list as well as through the bug database. Unfortunately, this
-has made it hard to easily track the patches. And without being able
-to easily track them, too many of them have been ignored.</p>
-
-<p>Patches must now be submitted through the bug database, at
-<a
-href="http://issues.apache.org/bugzilla/">http://issues.apache.org/bugzilla/</a>
-. You'll need to create a Bugzilla
-account there if you don't already have one. Submit the patch by
-first entering a new bug report. Be sure to specify APR for the
-product if the patch is for a file in srclib/apr or srclib/apr-util.
-The following information is very helpful, when it is available:</p>
-
-<ol>
- <li>explain how to reproduce the problem and how the patch has been
- tested</li>
-</ol>
-
-<p>After the bug report has been created, edit it again and specify
-<b>PatchAvailable</b> as a keyword and then add your patch as a new
-attachment.</p>
-
-<p>If you wish to discuss the patch on the developer's mailing list,
-prefix your subject line with "[PATCH <PR-number>]" to reference
-your patch submission.</p>
-
-<p>Be aware that the core developers tend to be very conservative
-about what makes it into the core of Apache. Apache has a very
-flexible API, and any advanced functionality is likely to be pushed to
-be a third-party module. Portability fixes are the most important;
-protocol correctness is also critical for us; and we're sure there's
-more dumb mistakes in the code than we could shake a stick at. Those
-will get priority; new functionality may not.</p>
-
-</section>
-
-<section id="ignored"><title>What if my patch gets ignored?</title>
-
-<p>Because Apache has only a small number of volunteer developers, and
-these developers are often very busy, it is possible that your patch
-will not receive any immediate feedback. Developers must prioritize
-their time, dealing first with serious bugs and with parts of the code
-in which they have interest and knowledge. Here are some suggestions
-on what you can do to encourage action on your patch:</p>
-
-<ol>
-
-<li>Be persistent but polite. Post to the developers list pointing
-out your patch and why you feel it is important. Feel free to do this
-about once a week and continue until you get a response. Just be sure
-to be polite about it, since the developers are unlikely to respond to
-rude messages.</li>
+1. <BLOCKQUOTE><CODE>tar xvzf httpd-2.0.x.tar.gz</CODE></BLOCKQUOTE>
-<li>Encourage other Apache users to review and test your patch, and then
-append a note to the bug report with the details. Developers are much more
-likely to review and commit a patch if they see that it has been widely
-tested.</li>
+1. <BLOCKQUOTE><CODE>cp -ax httpd-2.0.x httpd-2.0.x.new</CODE></BLOCKQUOTE>
+
+1. edit files in httpd-2.0.x.new and build/test
+
+1. <BLOCKQUOTE><CODE>cd /sources</CODE></BLOCKQUOTE>
+
+1. <BLOCKQUOTE><CODE>diff -ru httpd-2.0.x httpd-2.0.x.new
+>my.unified.diff.patch</CODE></BLOCKQUOTE>
+
+If your source tree was checked out of subversion,<BLOCKQUOTE><CODE>svn
+diff</CODE></BLOCKQUOTE>will create the patch in the correct format.
+
+# Submitting your Patch #
+
+Traditionally, patches have been submitted on the developer's mailing list
+as well as through the bug database. Unfortunately, this has made it hard
+to easily track the patches. And without being able to easily track them,
+too many of them have been ignored.
-<li>Make sure your patch is easy to read and apply. Follow all the
-style suggestions in the above sections and include any necessary
-documentation changes.</li>
-
-<li>Review the bugs database for similar errors. If there are
-duplicates, close them as duplicates of the initial report (this cross
-references the two bugs to each other.) Add an extra note when
-closing well documented dups if the particular bug report contains
-useful unique details. If there is a report that isn't identical, but
-might be helped by your patch, mark it as 'depends on' the bug report
-containing your patch. Finally mark the original incident as 'depends
-on' your bug report, with patch.</li>
-
-<li>Earn "brownie points" by dealing with other bug reports that you
-can politely and correctly address. As ugly as this job is -- sort of
-like the poop crew following a parade -- it leaves the principal
-committers with time to address the real bugs and their solutions
-instead of sweeping up the droppings.</li>
+Patches must now be submitted through the bug database, at
+[http://issues.apache.org/bugzilla/](http://issues.apache.org/bugzilla/).
+You'll need to create a Bugzilla account there if you don't already have
+one. Submit the patch by first entering a new bug report. Be sure to
+specify APR for the product if the patch is for a file in srclib/apr or
+srclib/apr-util. The following information is very helpful, when it is
+available:
+
+1. explain how to reproduce the problem and how the patch has been tested
+
+After the bug report has been created, edit it again and specify
+**PatchAvailable** as a keyword and then add your patch as a new
+attachment.
+
+If you wish to discuss the patch on the developer's mailing list, prefix
+your subject line with "[PATCH <PR-number>]" to reference your patch
+submission.
+
+Be aware that the core developers tend to be very conservative about what
+makes it into the core of Apache. Apache has a very flexible API, and any
+advanced functionality is likely to be pushed to be a third-party module.
+Portability fixes are the most important; protocol correctness is also
+critical for us; and we're sure there's more dumb mistakes in the code than
+we could shake a stick at. Those will get priority; new functionality may
+not.
+
+# What if my patch gets ignored? # {#ignored}
+
+Because Apache has only a small number of volunteer developers, and these
+developers are often very busy, it is possible that your patch will not
+receive any immediate feedback. Developers must prioritize their time,
+dealing first with serious bugs and with parts of the code in which they
+have interest and knowledge. Here are some suggestions on what you can do
+to encourage action on your patch:
+
+1. Be persistent but polite. Post to the developers list pointing out your
+patch and why you feel it is important. Feel free to do this about once a
+week and continue until you get a response. Just be sure to be polite about
+it, since the developers are unlikely to respond to rude messages.
+
+1. Encourage other Apache users to review and test your patch, and then
+append a note to the bug report with the details. Developers are much more
+likely to review and commit a patch if they see that it has been widely
+tested.
-</ol>
-</section>
+1. Make sure your patch is easy to read and apply. Follow all the style
+suggestions in the above sections and include any necessary documentation
+changes.
+
+1. Review the bugs database for similar errors. If there are duplicates,
+close them as duplicates of the initial report (this cross references the
+two bugs to each other.) Add an extra note when closing well documented
+dups if the particular bug report contains useful unique details. If there
+is a report that isn't identical, but might be helped by your patch, mark
+it as 'depends on' the bug report containing your patch. Finally mark the
+original incident as 'depends on' your bug report, with patch.
+
+1. Earn "brownie points" by dealing with other bug reports that you can
+politely and correctly address. As ugly as this job is -- sort of like the
+poop crew following a parade -- it leaves the principal committers with
+time to address the real bugs and their solutions instead of sweeping up
+the droppings.
-</body>
-</document>
Copied: httpd/site/trunk/content/dev/release.mdtext (from r1334802, httpd/site/trunk/content/dev/release.xml)
URL: http://svn.apache.org/viewvc/httpd/site/trunk/content/dev/release.mdtext?p2=httpd/site/trunk/content/dev/release.mdtext&p1=httpd/site/trunk/content/dev/release.xml&r1=1334802&r2=1334814&rev=1334814&view=diff
==============================================================================
--- httpd/site/trunk/content/dev/release.xml (original)
+++ httpd/site/trunk/content/dev/release.mdtext Sun May 6 22:53:19 2012
@@ -1,286 +1,291 @@
-<?xml version="1.0"?>
-<document>
- <properties>
- <author email="docs@httpd.apache.org">Documentation Group</author>
- <title>Apache HTTP Server Release Guidelines</title>
- </properties>
-<body>
-
-<section><title>Introduction</title>
-<p>This document describes the general release policies used by the
-Apache HTTP Server Project to create releases of httpd-2.2 (the current
-Apache 2.2 branch). Aside from the voting guidelines, this policy
-may be adjusted by the Release Manager.</p>
-
-<p>With the introduction of Apache 2.1, the Apache httpd project has
-adopted an odd-even release strategy, where development happens with
-alpha and beta releases assigned an odd-numbered minor version, and its
-general availability (stable) release is designed with the subsequent
-even-numbered minor version. E.g. 2.1.0-alpha through 2.1.6-alpha
-were followed by 2.1.7-beta through 2.1.9 beta, and cumulated in the
-2.2.0 general availability release.</p>
-</section>
-
-<section><title>Who can make a release?</title>
-<p>Technically, anyone can make a release of the source code due to the
-<a href="http://www.apache.org/licenses/">Apache Software License</a>.
-However, only members of the Apache HTTP Server Project (committers)
-can make a release designated as Apache HTTP Server (httpd). Other
-people must call their release something other than "Apache" unless
-they obtain written permission from the Apache Software Foundation.</p>
-
-<p>Following our official release policies, we will only accept release
-binaries from members of the Apache HTTP Server Project for inclusion on our
-website. This ensures that our binaries can be supported by members of
-the project. Other people are free to make binaries, but we will not
-post them on our website.</p>
-</section>
-
-<section><title>Who is in charge of a release?</title>
-<p>The release is coordinated by a Release Manager (hereafter, abbreviated
-as RM). Since this job requires trust, coordination of the development
-community, and access to subversion, only committers to the project can be RM.
-However, there is no set RM, and more than one RM can be active at a time.
-Any committer may create a release candidate, provided that it is based on
-a releasable (non-vetoed) tag of our current subversion repository
-corresponding to the target version number. In order to facilitate
+Title: Apache HTTP Server Release Guidelines
+Notice: 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.
+
+This document describes the general release policies used by the Apache
+HTTP Server Project to create releases of httpd-2.2 (the current Apache 2.2
+branch). Aside from the voting guidelines, this policy may be adjusted by
+the Release Manager.
+
+With the introduction of Apache 2.1, the Apache httpd project has adopted
+an odd-even release strategy, where development happens with alpha and beta
+releases assigned an odd-numbered minor version, and its general
+availability (stable) release is designed with the subsequent even-numbered
+minor version. E.g. 2.1.0-alpha through 2.1.6-alpha were followed by
+2.1.7-beta through 2.1.9 beta, and cumulated in the 2.2.0 general
+availability release.
+
+# Who can make a release? #
+
+Technically, anyone can make a release of the source code due to the
+[Apache Software License](http://www.apache.org/licenses/). However, only
+members of the Apache HTTP Server Project (committers) can make a release
+designated as Apache HTTP Server (httpd). Other people must call their
+release something other than "Apache" unless they obtain written permission
+from the Apache Software Foundation.
+
+Following our official release policies, we will only accept release
+binaries from members of the Apache HTTP Server Project for inclusion on
+our website. This ensures that our binaries can be supported by members of
+the project. Other people are free to make binaries, but we will not post
+them on our website.
+
+# Who is in charge of a release? #
+
+The release is coordinated by a Release Manager (hereafter, abbreviated as
+RM). Since this job requires trust, coordination of the development
+community, and access to subversion, only committers to the project can be
+RM. However, there is no set RM, and more than one RM can be active at a
+time. Any committer may create a release candidate, provided that it is
+based on a releasable (non-vetoed) tag of our current subversion repository
+corresponding to the target version number. In order to facilitate
communication, it is deemed nice to alert the community to your planned
release schedule before creating the release candidate, since some other
-folks may be on the verge of committing an important change (or backing out an
-error). A release candidate should only be made when there is an intention
-to propose it for a vote on public release. There are no "private" releases at Apache.</p>
-</section>
-
-<section><title>Who may make a good candidate for an RM?</title>
-<p>Someone with lots of time to kill. Being an RM is a very important job
-in our community because it takes a fair amount of time to produce a stable
-release. If you feel lucky, a release could be distributed without testing,
-but our experience has shown that this leads to a higher number of <i>dud</i>
-releases. In general, our experience has shown that a well-coordinated
-release fares better than non-coordinated releases.</p>
-</section>
-
-<section><title>When do I know if it is a good time to release?</title>
-<p>Generally speaking, when some useful changes have been applied since
-the last release and there are no showstoppers left to be resolved.
-It is our convention to indicate <i>showstoppers</i> in the STATUS
-file in the repository. A showstopper entry does not imply that a release
-cannot be made -- it is more of an indication of current project consensus
-and a reminder of what fixes are on the critical path. Each RM gets to
-choose when to cut a release candidate based on the current content of
-subversion. The entire PMC gets to decide whether or not that candidate
-deserves to be released.</p>
-
-<p>An item being denoted in STATUS as a <i>showstopper</i> indicates that
-someone believes the issue must be resolved before the next release,
-and the RM is going to hold off until it is resolved or moved out of
-the showstopper category. These items may be bugs, outstanding vetos
-that have not yet been resolved, or enhancements that must make it into the
-release. Note that the RM may also add showstopper entries to indicate
-what issues must be resolved before they personally are willing to cut
-a release candidate, though they cannot prevent others from taking on
-the RM job and proposing a release candidate of their own.</p>
-</section>
-
-<section><title>What power does the RM yield?</title>
-<p>The only power held by the RM is the right to determine when the
-current content of subversion is worth their own effort in cutting
-a release candidate. The only thing the RM has authority over is the
-building of a source package, based on the contents of our subversion,
-that can then be put up for vote. They can decide what snapshot revision
-to tag for a candidate. They can decide to branch early and build candidates
-based on the branch rather than a more active development tree, but they
-cannot prevent others from working on that branch as well.
-They can also decide not to build anything at all. They can
-do all sorts of organizational support, advocacy, pleading, or
-whatever in order to encourage the rest of the project committers to
-apply changes, test the candidate, vote for things under issue, etc.</p>
-
-<p>The RM is not a dictator (benevolent or not). They do not have the
-right to pick apart or select any variation of the product they might like
-to release: it has to be a specific tag or revision (moment in time) that
-is present in our subversion and applicable to the version number
-targeted for the release. If there is something they don't like in
-the tree, then they have the same right as other PMC members to change
-or veto that code first, make the change to subversion, and then build
-the release candidate. Likewise, the RM cannot include in the candidate
-any change that has been vetoed by others, and their candidate cannot
-be released if it contains any changes that have been vetoed
-since it was built. The RM has the right to kill their own candidate
-if they learn something during the release process that they think,
-for whatever reason, causes the build to be unreleasable. But the
-RM can't stop anyone else on the PMC from taking the same candidate
-and calling for its release under their own management as RM.</p>
-</section>
-
-<section><title>How can an RM be confident in a release?</title>
-<p>The RM may perform sanity checks on release candidates. One highly
-recommended suggestion is to run the httpd-test suite against the candidate.
-The release candidate should pass all of the relevant tests before making
-it official, and certainly avoid new regressions (tests that previously
-passed, and now fail).</p>
-
-<p>Another good idea is to coordinate running a candidate on apache.org for
-a period of time. This will require coordination with the infrastructure
-team.
-In the past, the group has liked to see approximately 48-72 hours of
+folks may be on the verge of committing an important change (or backing out
+an error). A release candidate should only be made when there is an
+intention to propose it for a vote on public release. There are no
+"private" releases at Apache.
+
+# Who may make a good candidate for an RM? #
+
+Someone with lots of time to kill. Being an RM is a very important job in
+our community because it takes a fair amount of time to produce a stable
+release. If you feel lucky, a release could be distributed without testing,
+but our experience has shown that this leads to a higher number of *dud*
+releases. In general, our experience has shown that a well-coordinated
+release fares better than non-coordinated releases.
+
+# When do I know if it is a good time to release? #
+
+Generally speaking, when some useful changes have been applied since the
+last release and there are no showstoppers left to be resolved. It is our
+convention to indicate *showstoppers* in the STATUS file in the repository.
+A showstopper entry does not imply that a release cannot be made -- it is
+more of an indication of current project consensus and a reminder of what
+fixes are on the critical path. Each RM gets to choose when to cut a
+release candidate based on the current content of subversion. The entire
+PMC gets to decide whether or not that candidate deserves to be released.
+
+An item being denoted in STATUS as a *showstopper* indicates that someone
+believes the issue must be resolved before the next release, and the RM is
+going to hold off until it is resolved or moved out of the showstopper
+category. These items may be bugs, outstanding vetos that have not yet been
+resolved, or enhancements that must make it into the release. Note that the
+RM may also add showstopper entries to indicate what issues must be
+resolved before they personally are willing to cut a release candidate,
+though they cannot prevent others from taking on the RM job and proposing a
+release candidate of their own.
+
+# What power does the RM yield? #
+
+The only power held by the RM is the right to determine when the current
+content of subversion is worth their own effort in cutting a release
+candidate. The only thing the RM has authority over is the building of a
+source package, based on the contents of our subversion, that can then be
+put up for vote. They can decide what snapshot revision to tag for a
+candidate. They can decide to branch early and build candidates based on
+the branch rather than a more active development tree, but they cannot
+prevent others from working on that branch as well. They can also decide
+not to build anything at all. They can do all sorts of organizational
+support, advocacy, pleading, or whatever in order to encourage the rest of
+the project committers to apply changes, test the candidate, vote for
+things under issue, etc.
+
+The RM is not a dictator (benevolent or not). They do not have the right to
+pick apart or select any variation of the product they might like to
+release: it has to be a specific tag or revision (moment in time) that is
+present in our subversion and applicable to the version number targeted for
+the release. If there is something they don't like in the tree, then they
+have the same right as other PMC members to change or veto that code first,
+make the change to subversion, and then build the release candidate.
+Likewise, the RM cannot include in the candidate any change that has been
+vetoed by others, and their candidate cannot be released if it contains any
+changes that have been vetoed since it was built. The RM has the right to
+kill their own candidate if they learn something during the release process
+that they think, for whatever reason, causes the build to be unreleasable.
+But the RM can't stop anyone else on the PMC from taking the same candidate
+and calling for its release under their own management as RM.
+
+# How can an RM be confident in a release? #
+
+The RM may perform sanity checks on release candidates. One highly
+recommended suggestion is to run the httpd-test suite against the
+candidate. The release candidate should pass all of the relevant tests
+before making it official, and certainly avoid new regressions (tests that
+previously passed, and now fail).
+
+Another good idea is to coordinate running a candidate on apache.org for a
+period of time. This will require coordination with the infrastructure
+team. In the past, the group has liked to see approximately 48-72 hours of
usage in production to certify that the release is functional in the real
-world. Note that some committers may choose to not vote on a release until
-feedback has been gathered from the apache.org instance running the release.
-This is not a requirement (each committer is free to come up with their own
-personal voting guidelines), but it produces a feeling of confidence in the
-release that it will not be a <i>dud</i>.</p>
-</section>
-
-<section><title>How to do a release?</title>
-<p>Once the tree has been suitably tested by the RM and any other interested
-parties, they should "roll" a candidate tarball for potential release.</p>
-
-<p>Key points:</p>
-<ol>
-<li>Execute <code>./build.sh all</code> in case of the 2.2.x documentation and
-<code>./build.sh all convmap</code> in case of the 2.2.x documentation to
-ensure that the documentation transformations are up to date.</li>
-<li>Ensure that the RM's PGP/GPG key is in the httpd-dist/KEYS file.</li>
-<li>Set <code>AP_SERVER_DEVBUILD_BOOLEAN</code> to <code>0</code> in
-<code>include/ap_release.h</code> in case of 2.2.x and set
-<code>AP_SERVER_ADD_STRING</code> to <code>""</code> in case of 2.2.x.</li>
-<li>Create an official X.Y.Z tag based on the candidate tree.</li>
-<li>Revert the changes done to <code>include/ap_release.h</code> and bump
-<code>AP_SERVER_PATCHLEVEL_NUMBER</code>.</li>
-<li>Bump <code>ENTITY httpd.patch</code> in
-<code>docs/manual/style/version.ent</code>.</li>
-<li>Note the tag date in the STATUS file.</li>
-<li>Run the httpd/site/trunk/tools/release.sh script.</li>
-<li>Commit the generated release tarballs and signatures to the subversion
-https://dist.apache.org/repos/dist/dev/httpd/ repository.</li>
-<li>Email dev@httpd.apache.org with a [VOTE] Release X.Y.Z to call
-for testing and votes on this candidate.</li>
-</ol>
-</section>
-
-<section><title>What can I call this release?</title>
-<p>At this point, this tarball/archive is not yet a release.</p>
-
-<p>Based on the communities confidence in the code, the next step is
-to issue a release vote as alpha, beta or general availability (GA)
-candidate. The Apache HTTP Server Project has three classifications
-for its releases:</p>
-
-<ul>
-<li>Alpha</li>
-<li>Beta</li>
-<li>General Availability (GA)</li>
-</ul>
-
-<p>Alpha indicates that the release is not meant for mainstream usage or
-may have serious problems that prohibits its use. The initial releases
-off of the x.{odd}.z development branches are considered alpha quality.</p>
-
-<p>Beta indicates that the x.{odd}.z development branch is nearing
-completion and will soon ship as a x.{even}.0 GA release. This indicates
-that it is expected to compile and perform basic tasks. However, there
-may be problems with this release that inhibit its widespread adoption.</p>
-
-<p>General Availability (GA) indicates that this release is the best
-available version and is recommended for all usage. It also indicates
-that this release replaces all previous GA versions, and it's interfaces
-should remain stable throughout the life of this x.y version. (Those
-interfaces that are in flux are designated <i>experimental</i>.)</p>
-
-<p>Finally, remember version numbers are cheap. If x.y.13 is retracted
-due to a flaw or prior veto or simply because of 'one more change' to add
-to this next release, then the RM should designate x.y.14. Don't attempt
-to overload an earlier tarball with additional changes, simply keep moving.</p>
-</section>
-
-<section><title>Who can vote?</title>
-<p>For the ASF to release the candidate tarball/archive, at least three
-project members must vote affirmatively for release, and there must be more
-positive than negative votes for the release. There is no 'veto' to a
-release vote. A previous veto of specific code can and should be called
-out to the RM if it was mistakenly included. A new tarball release
-candidate should be rolled without the offending code if this
-is the case.</p>
-
-<p>Non-committers may cast a vote for a release's quality. In fact,
-this is extremely encouraged as it provides much-needed feedback to
-the community about the release's quality. However, only binding
-votes cast by PMC members count towards the designation.</p>
-
-<p>Finally, note that votes are on <i>source code</i> tarballs, and only the
-source code is authoritative. Binaries, while helpful, are considered
-other artifacts and must be generated from the exact source code contained
-in the release. If a patch is unavoidable for a specific platform, the
-applicable patches MUST be made available alongside the platform binaries.</p>
-</section>
-
-<section><title>How do we make it public?</title>
-<p>Once the release has reached the highest-available designation (as deemed
-by the RM), the release can be moved to the httpd distribution directory
-on apache.org. The release tarballs and signatures can be svn mv'ed from
-the https://dist.apache.org/repos/dist/dev/httpd/ repository across to the
-https://dist.apache.org/repos/dist/release/httpd/ repository. In that
+world. Note that some committers may choose to not vote on a release until
+feedback has been gathered from the apache.org instance running the
+release. This is not a requirement (each committer is free to come up with
+their own personal voting guidelines), but it produces a feeling of
+confidence in the release that it will not be a *dud*.
+
+# How to do a release? #
+
+Once the tree has been suitably tested by the RM and any other interested
+parties, they should "roll" a candidate tarball for potential release.
+
+Key points:
+
+1. Execute `./build.sh all` in case of the 2.2.x documentation and
+`./build.sh all convmap` in case of the 2.2.x documentation to ensure that
+the documentation transformations are up to date.
+
+1. Ensure that the RM's PGP/GPG key is in the httpd-dist/KEYS file.
+
+1. Set `AP_SERVER_DEVBUILD_BOOLEAN` to `0` in `include/ap_release.h` in
+case of 2.2.x and set `AP_SERVER_ADD_STRING` to `""` in case of 2.2.x.
+
+1. Create an official X.Y.Z tag based on the candidate tree.
+
+1. Revert the changes done to `include/ap_release.h` and bump
+`AP_SERVER_PATCHLEVEL_NUMBER`.
+
+1. Bump `ENTITY httpd.patch` in `docs/manual/style/version.ent`.
+
+1. Note the tag date in the STATUS file.
+
+1. Run the httpd/site/trunk/tools/release.sh script.
+
+1. Commit the generated release tarballs and signatures to the subversion
+https://dist.apache.org/repos/dist/dev/httpd/ repository.
+
+1. Email dev@httpd.apache.org with a [VOTE] Release X.Y.Z to call for
+testing and votes on this candidate.
+
+# What can I call this release? #
+
+At this point, this tarball/archive is not yet a release.
+
+Based on the communities confidence in the code, the next step is to issue
+a release vote as alpha, beta or general availability (GA) candidate. The
+Apache HTTP Server Project has three classifications for its releases:
+
+- Alpha
+
+- Beta
+
+- General Availability (GA)
+
+Alpha indicates that the release is not meant for mainstream usage or may
+have serious problems that prohibits its use. The initial releases off of
+the x.{odd}.z development branches are considered alpha quality.
+
+Beta indicates that the x.{odd}.z development branch is nearing completion
+and will soon ship as a x.{even}.0 GA release. This indicates that it is
+expected to compile and perform basic tasks. However, there may be problems
+with this release that inhibit its widespread adoption.
+
+General Availability (GA) indicates that this release is the best available
+version and is recommended for all usage. It also indicates that this
+release replaces all previous GA versions, and it's interfaces should
+remain stable throughout the life of this x.y version. (Those interfaces
+that are in flux are designated *experimental*.)
+
+Finally, remember version numbers are cheap. If x.y.13 is retracted due to
+a flaw or prior veto or simply because of 'one more change' to add to this
+next release, then the RM should designate x.y.14. Don't attempt to
+overload an earlier tarball with additional changes, simply keep moving.
+
+# Who can vote? #
+
+For the ASF to release the candidate tarball/archive, at least three
+project members must vote affirmatively for release, and there must be more
+positive than negative votes for the release. There is no 'veto' to a
+release vote. A previous veto of specific code can and should be called out
+to the RM if it was mistakenly included. A new tarball release candidate
+should be rolled without the offending code if this is the case.
+
+Non-committers may cast a vote for a release's quality. In fact, this is
+extremely encouraged as it provides much-needed feedback to the community
+about the release's quality. However, only binding votes cast by PMC
+members count towards the designation.
+
+Finally, note that votes are on *source code* tarballs, and only the source
+code is authoritative. Binaries, while helpful, are considered other
+artifacts and must be generated from the exact source code contained in the
+release. If a patch is unavoidable for a specific platform, the applicable
+patches MUST be made available alongside the platform binaries.
+
+# How do we make it public? #
+
+Once the release has reached the highest-available designation (as deemed
+by the RM), the release can be moved to the httpd distribution directory on
+apache.org. The release tarballs and signatures can be svn mv'ed from the
+https://dist.apache.org/repos/dist/dev/httpd/ repository across to the
+https://dist.apache.org/repos/dist/release/httpd/ repository. In that
release tree are also the patches/, subproject/ and binaries/ distribution
-trees.</p>
+trees.
-<p>It should be ensured that the release is also added to
-Bugzilla by sending a mail to dev@httpd.apache.org requesting the same. The
-request is picked up there by one of the project members with Bugzilla
-administrator permissions and the release is added to Bugzilla. Also do
-not forget to bump the version number in the projects doap file
-(<code>httpd/site/trunk/docs/doap.rdf</code>). Approximately
-24 to 48 hours after the files have been moved, a public announcement can be
-made. We wait this period so that the mirrors can receive the new release
-before the announcement. An email can then be sent to the announcements lists
-(announce@apache.org, announce@httpd.apache.org). Drafts of the announcement
-are usually posted on the development list before sending the announcement to
-let the community clarify any issues that we feel should be addressed in the
-announcement.</p>
-</section>
-
-<section><title>Should the announcement wait for binaries?</title>
-<p>In short, no. The only files that are required for a public release
-are the source tarballs (.tar.Z, .tar.gz). Volunteers can provide
-the Win32 source distribution and binaries, and other esoteric
-binaries.</p>
-
-<p>Note that the typical Win32 source distribution differs from the
-original tarball in that it has generated project files as well as
-the CRLF line endings required for that platform. More information
-can be found <a
-href="http://httpd.apache.org/docs-2.0/platform/win_compiling.html">here</a>.
-</p>
-</section>
-
-<section><title>Oops. We found a problem.</title>
-<p>At this point, the release has been created. No code changes can be
-made in this release. If a problem is found, it will have to be addressed
-in the next release or a patch can be made available. No changes can
-be made between alpha, beta, and GA status. The only difference is the
-file name that is downloaded by the users. If an alpha tarball is created,
-but there was an error that can be resolved by re-rolling the tarball,
-it may be permissible to re-roll the release. But, the code itself may
-<font color="red">not</font> change from designation to designation.</p>
-
-<p>There are two courses of action:</p>
-
-<p>Revoke the release and immediately create another one that has a fix
-to this problem. You can take the old release, apply the single patch,
-and start the voting process again. This is only recommended for
-critical problems found early on in the release cycle.</p>
+It should be ensured that the release is also added to Bugzilla by sending
+a mail to dev@httpd.apache.org requesting the same. The request is picked
+up there by one of the project members with Bugzilla administrator
+permissions and the release is added to Bugzilla. Also do not forget to
+bump the version number in the projects doap file (
+`httpd/site/trunk/docs/doap.rdf` ). Approximately 24 to 48 hours after the
+files have been moved, a public announcement can be made. We wait this
+period so that the mirrors can receive the new release before the
+announcement. An email can then be sent to the announcements lists
+(announce@apache.org, announce@httpd.apache.org). Drafts of the
+announcement are usually posted on the development list before sending the
+announcement to let the community clarify any issues that we feel should be
+addressed in the announcement.
+
+# Should the announcement wait for binaries? #
+
+In short, no. The only files that are required for a public release are the
+source tarballs (.tar.Z,.tar.gz). Volunteers can provide the Win32 source
+distribution and binaries, and other esoteric binaries.
+
+Note that the typical Win32 source distribution differs from the original
+tarball in that it has generated project files as well as the CRLF line
+endings required for that platform. More information can be found
+[here](http://httpd.apache.org/docs-2.0/platform/win_compiling.html).
+
+# Oops. We found a problem. #
+
+At this point, the release has been created. No code changes can be made in
+this release. If a problem is found, it will have to be addressed in the
+next release or a patch can be made available. No changes can be made
+between alpha, beta, and GA status. The only difference is the file name
+that is downloaded by the users. If an alpha tarball is created, but there
+was an error that can be resolved by re-rolling the tarball, it may be
+permissible to re-roll the release. But, the code itself may<font
+color="red">not</font>change from designation to designation.
+
+There are two courses of action:
+
+Revoke the release and immediately create another one that has a fix to
+this problem. You can take the old release, apply the single patch, and
+start the voting process again. This is only recommended for critical
+problems found early on in the release cycle.
-<p>If the problem is less severe, place the patch to the problem in the
-/dist/httpd/patches/apply_to_X.Y.Z directory. A link to this directory
+If the problem is less severe, place the patch to the problem in the
+/dist/httpd/patches/apply_to_X.Y.Z directory. A link to this directory
should be included in the release notes with descriptions as to what
-problem each patch addresses.</p>
-</section>
+problem each patch addresses.
+
+# Suggestions? #
-<section><title>Suggestions?</title>
-<p>As always, if you have any suggestions or comments on our process,
-please feel free to email our developer mailing list with your comments.
-We hope you found this document useful.</p>
-</section>
+As always, if you have any suggestions or comments on our process, please
+feel free to email our developer mailing list with your comments. We hope
+you found this document useful.
-</body>
-</document>
Copied: httpd/site/trunk/content/dev/styleguide.mdtext (from r1334802, httpd/site/trunk/content/dev/styleguide.xml)
URL: http://svn.apache.org/viewvc/httpd/site/trunk/content/dev/styleguide.mdtext?p2=httpd/site/trunk/content/dev/styleguide.mdtext&p1=httpd/site/trunk/content/dev/styleguide.xml&r1=1334802&r2=1334814&rev=1334814&view=diff
==============================================================================
--- httpd/site/trunk/content/dev/styleguide.xml (original)
+++ httpd/site/trunk/content/dev/styleguide.mdtext Sun May 6 22:53:19 2012
@@ -1,244 +1,192 @@
-<?xml version="1.0"?>
-<document>
- <properties>
- <author email="docs@httpd.apache.org">Documentation Group</author>
- <title>Apache Developers' C Language Style Guide</title>
- </properties>
-<body>
-
-<section>
-<title>Apache Developers' C Language Style Guide</title>
-
-<strong>Compiled by Paul Sutton <a
-href="mailto:paul@awe.com">paul@awe.com</a></strong>. Based on a vote
-taken in November, 1996.
-<br />
-Further refinements voted upon in July 1997.
-</section>
-
-<section>
-<title>Introduction</title>
-<p>[This bit could state that code should be laid out to be clear to
-someone else familiar with Apache. Functions should be short and
-easily understood. Comments should be provided to explain the
-rationale for code which is not obvious, and to document behavior of
-functions. The guidelines can be broken if necessary to achieve a
-clearer layout]</p>
-
-<p>This style can be generated with the following arguments to GNU indent:</p>
-
-<p><ul><code>-i4 -npsl -di0 -br -nce -d0 -cli0 -npcs -nfc1 -nut</code></ul></p>
-
-</section>
-
-<section>
-<title>The Guidelines</title>
- <UL>
- <li>Opening braces are given on the same lines as statements, or on the
- following line at the start of a function definition.
- </li>
- <li>Code inside a block (whether surrounded by braces or not) is
- indented by four space characters. Tab characters are not
- used. Comments are indented to the same level as the surrounding
- code.
- </li>
- <li>Closing braces are always on a separate line from surrounding
- code, and are indented to line up with the start of the text on
- the line containing the corresponding opening brace.
- </li>
- <li>Functions are declared with ANSI-style arguments.
- </li>
- <li>There is no space between the function name and the opening bracket
- of the arguments to the function. There is a single space following
- commas in argument lists and the semi-colons in for statements.
- </li>
- <li>Inside a <samp>switch()</samp> statement, the <samp>case</samp>
- keywords are indented to the same level as the <samp>switch</samp> line.
- </li>
- <li>Operators in expressions should be surrounded by a single space
- before and after, except for unary increment (++), decrement (--), and
- negation (!) operators.
- </li>
- <li>There is no whitespace between a cast and the item modified
- (<EM>e.g.</EM>, "<samp>(int)j</samp>" and not
- "<samp>(int) j</samp>").
- </li>
- <li>If a cast is to a pointer type, there is a space between the type
- and the <samp>*</samp> character (<EM>e.g.</EM>,
- "<samp>(char *)i</samp>" instead of
- "<samp>(char*)i</samp>")
- </li>
- </UL>
-</section>
-
-<section>
-<title>Details and Examples</title>
-
-<ol>
-<li id="ex-indentation"><strong>Indentation, General Style</strong>
-
-<p>Each level of indentation of code is four spaces. Tab characters
- should never be used. Specific indentation rules for function
- declarations and control-flow keywords are given below.</p>
+Title: Apache Developers' C Language Style Guide
+Notice: 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.
+
+**Compiled by Paul Sutton [paul@awe.com](mailto:paul@awe.com) **. Based on
+a vote taken in November, 1996.<br></br>Further refinements voted upon in
+July 1997.
+
+# Introduction #
+
+[This bit could state that code should be laid out to be clear to someone
+else familiar with Apache. Functions should be short and easily understood.
+Comments should be provided to explain the rationale for code which is not
+obvious, and to document behavior of functions. The guidelines can be
+broken if necessary to achieve a clearer layout]
+
+This style can be generated with the following arguments to GNU indent:
+
+`-i4 -npsl -di0 -br -nce -d0 -cli0 -npcs -nfc1 -nut`
+
+# The Guidelines #
+<UL><li>Opening braces are given on the same lines as statements, or on the
+following line at the start of a function definition.</li><li>Code inside a
+block (whether surrounded by braces or not) is indented by four space
+characters. Tab characters are not used. Comments are indented to the same
+level as the surrounding code.</li><li>Closing braces are always on a
+separate line from surrounding code, and are indented to line up with the
+start of the text on the line containing the corresponding opening
+brace.</li><li>Functions are declared with ANSI-style
+arguments.</li><li>There is no space between the function name and the
+opening bracket of the arguments to the function. There is a single space
+following commas in argument lists and the semi-colons in for
+statements.</li><li>Inside a<samp>switch()</samp>statement,
+the<samp>case</samp>keywords are indented to the same level as
+the<samp>switch</samp>line.</li><li>Operators in expressions should be
+surrounded by a single space before and after, except for unary increment
+(++), decrement (--), and negation (!) operators.</li><li>There is no
+whitespace between a cast and the item modified (<EM>e.g.</EM>,
+"<samp>(int)j</samp>" and not "<samp>(int) j</samp>").</li><li>If a cast is
+to a pointer type, there is a space between the type and
+the<samp>*</samp>character (<EM>e.g.</EM>, "<samp>(char *)i</samp>" instead
+of "<samp>(char*)i</samp>")</li></UL>
+
+# Details and Examples #
+
+1. **Indentation, General Style**
+Each level of indentation of code is four spaces. Tab characters should
+never be used. Specific indentation rules for function declarations and
+control-flow keywords are given below.
-<p>Example:</p>
-<pre>
+Example:
+`
main(int argc, char **argc)
{
- if (argc != 0) {
- fprintf(stderr, "No arguments allowed\n");
- exit(1);
- }
- exit(0);
+ if (argc != 0) {
+ fprintf(stderr, "No arguments allowed\n");
+ exit(1);
+ }
+ exit(0);
}
-</pre>
+`
+<A NAME="long-exps">If an expression</A>(or a routine declaration or
+invocation) would extend past column 80, the terms or arguments are wrapped
+at a convenient spot and the wrapped portion is indented under the first
+term in the expression (or the first argument to the function). Conditional
+expressions should be wrapped to keep single or parenthesized terms as
+atomic as possible, and place Boolean operators at either the start
+(preferable) or end of the line.
-<p><A NAME="long-exps">If an expression</A> (or a routine declaration or
-invocation) would extend
-past column 80, the terms or arguments are wrapped at a convenient spot
-and the wrapped portion is indented under the first term in the expression
-(or the first argument to the function).
-Conditional expressions should be wrapped to keep single or
-parenthesized terms as atomic as possible, and place Boolean operators
-at either the start (preferable) or end of the line.
-</p>
-<p>
Example:
-</p>
-<pre>
+`
static const char *really_long_name(int i, int j,
- const char *args, void *foo,
- int k)
+ const char *args, void *foo,
+ int k)
if (cond1 && (item2 || item3) && (!item4)
- && (item5 || item6) && item7) {
- do_a_thing();
+ && (item5 || item6) && item7) {
+ do_a_thing();
}
-</pre>
-</li>
-<li id="ex-comments"><strong>Comments</strong>
-
-<p>Provide comments which explain the function of code where it is not
- clear from the code itself. Provide rationale where necessary for
- particular bits of code.</p>
+`
-<p>Comments should be indented to same level as the surrounding text.</p>
+1. **Comments**
+Provide comments which explain the function of code where it is not clear
+from the code itself. Provide rationale where necessary for particular bits
+of code.
-<p>Example:</p>
+Comments should be indented to same level as the surrounding text.
-<pre>
+Example:
+`
code;
/* comment */
code;
-</pre>
-</li>
-<li id="ex-func-decl"><strong>Function Declaration and Layout</strong>
-
-<p>Functions are laid out as follows:</p>
+`
-<pre>
+1. **Function Declaration and Layout**
+Functions are laid out as follows:
+`
int main(int argc, char **argv)
{
- code;
+ code;
}
-</pre>
-
-<p>The return type is placed on the same line as the function. Arguments
- (if any) are given in ANSI style. If no arguments, declare function
- as <samp>void</samp>. No space
- between function name and opening bracket, single space after comma
- separating each argument. The opening brace is placed on the line
- after the definition, indented to line up with the start of the
- return type text. The code is indented with four spaces, and the closing
- brace is indented to line up with the opening brace. <strong>Also
- see the section on indenting <A HREF="#long-exps">long declarations
- and invocations</A>.</strong></p>
-</li>
-<li id="ex-func-calls"><strong>Function Calls</strong>
-
-<p>Space after commas in function calls. No space between function name
- and opening bracket.</p>
-<pre>
+`
+The return type is placed on the same line as the function. Arguments (if
+any) are given in ANSI style. If no arguments, declare function
+as<samp>void</samp>. No space between function name and opening bracket,
+single space after comma separating each argument. The opening brace is
+placed on the line after the definition, indented to line up with the start
+of the return type text. The code is indented with four spaces, and the
+closing brace is indented to line up with the opening brace. **Also see the
+section on indenting<A HREF="#long-exps">long declarations and
+invocations</A>.**
+
+1. **Function Calls**
+Space after commas in function calls. No space between function name and
+opening bracket.
+`
f(a, b);
-</pre>
-<p><strong>Also
- see the section on indenting <A HREF="#long-exps">long declarations
- and invocations</A>.</strong>
-</p>
-</li>
-<li id="ex-flow"><strong>Flow-Control Layout</strong>
-
-<p>Flow-control statements (<samp>if</samp>, <samp>while</samp>,
- <samp>for</samp>, <EM>etc.</EM>) are laid out as in this example:</p>
-
-<pre>
+`
+**Also see the section on indenting<A HREF="#long-exps">long declarations
+and invocations</A>.**
+
+1. **Flow-Control Layout**
+Flow-control statements
+(<samp>if</samp>,<samp>while</samp>,<samp>for</samp>,<EM>etc.</EM>) are
+laid out as in this example:
+`
if (expr) {
- code;
+ code;
}
else {
- code;
+ code;
}
-</pre>
-
-<p>There is a space between the keyword and the opening bracket.
- Opening brace placed on same line as the flow keyword. The code
- itself is indented by four spaces. The closing brace is indented to
- line up with the opening brace. If an <samp>else</samp> clause is used, the
- <samp>else</samp> keyword is placed on the line following the closing
- brace and is indented to line up with the corresponding
- <samp>if</samp>. <strong>Also
- see the section on indenting <A HREF="#long-exps">long
- expressions</A>.</strong>
-</p>
-</li>
-
-<li id="ex-for"><strong><samp>for</samp> Layout</strong>
-
-<p>Space after the semi-colons. Example:</p>
-
-<pre>
+`
+There is a space between the keyword and the opening bracket. Opening brace
+placed on same line as the flow keyword. The code itself is indented by
+four spaces. The closing brace is indented to line up with the opening
+brace. If an<samp>else</samp>clause is used, the<samp>else</samp>keyword is
+placed on the line following the closing brace and is indented to line up
+with the corresponding<samp>if</samp>. **Also see the section on
+indenting<A HREF="#long-exps">long expressions</A>.**
+
+1. **<samp>for</samp>Layout**
+Space after the semi-colons. Example:
+`
for (a; b; c)
-</pre>
-</li>
-
-<li id="ex-switch"><strong><samp>switch</samp> Layout</strong>
-
-<p><samp>case</samp> lines within a <samp>switch()</samp> are indented to
- same level as the switch
- statement itself. The code for each case is indented by four spaces.
- Braces are laid out as for other control-flow keywords. Example:</p>
+`
-<pre>
+1. **<samp>switch</samp>Layout**
+<samp>case</samp>lines within a<samp>switch()</samp>are indented to same
+level as the switch statement itself. The code for each case is indented by
+four spaces. Braces are laid out as for other control-flow keywords.
+Example:
+`
switch (x) {
case a:
- code;
+ code;
case b:
- code;
+ code;
}
-</pre>
-</li>
-
-<li id="ex-expressions"><strong>Expressions</strong>
-
-<p>Space before and after assignment and other and operators. No space
- between unary operators (increment, decrement, and negation) and the
- lvalue. Examples:</p>
+`
-<pre>
+1. **Expressions**
+Space before and after assignment and other and operators. No space between
+unary operators (increment, decrement, and negation) and the lvalue.
+Examples:
+`
a = b
a + b
a < b
a = -b
a = !b
++a
-</pre>
-</li>
+`
-<li id="ex-enums"><strong>Capitalisation of Enums</strong>
-<p>No rule.</p>
-</li>
-</ol>
-</section>
+1. **Capitalisation of Enums**
+No rule.
-</body>
-</document>
Copied: httpd/site/trunk/content/dev/verification.mdtext (from r1334802, httpd/site/trunk/content/dev/verification.xml)
URL: http://svn.apache.org/viewvc/httpd/site/trunk/content/dev/verification.mdtext?p2=httpd/site/trunk/content/dev/verification.mdtext&p1=httpd/site/trunk/content/dev/verification.xml&r1=1334802&r2=1334814&rev=1334814&view=diff
==============================================================================
--- httpd/site/trunk/content/dev/verification.xml (original)
+++ httpd/site/trunk/content/dev/verification.mdtext Sun May 6 22:53:19 2012
@@ -1,176 +1,160 @@
-<?xml version="1.0"?>
-<document>
- <properties>
- <author email="docs@httpd.apache.org">Documentation Group</author>
- <title>Verifying Apache HTTP Server Releases</title>
- </properties>
-<body>
-
-<section id="Sign">
-<title>What we sign</title>
-
-<p>All official releases of code distributed by the Apache HTTP Server Project
-are signed by the release manager for the release. PGP signatures and MD5
-hashes are available along with the distribution.</p>
-
-<p>You should download the PGP signatures and MD5 hashes directly from the
-Apache Software Foundation rather than our mirrors. This is to help ensure the
-integrity of the signature files. However, you are encouraged to download the
-releases from our mirrors. (Our download page points you at the mirrors for
-the release and the official site for the signatures, so this happens
-automatically for you.)</p>
-
-</section>
-
-<section id="Checking">
-<title>Checking Signatures</title>
-
-<p>The following example details how signature interaction works. In this
-example, you are already assumed to have downloaded
-<code>httpd-2.0.44.tar.gz</code> (the release) and
-<code>httpd-2.0.44.tar.gz.asc</code> (the detached signature).</p>
-
-<p>This example uses <a href="http://www.gnupg.org/">The GNU Privacy Guard</a>.
-Any <a href="http://www.openpgp.org/">OpenPGP</a>-compliant program should work
-successfully.</p>
-
-<p>First, we will check the detached signature
-(<code>httpd-2.0.44.tar.gz.asc</code>) against our release
-(<code>httpd-2.0.44.tar.gz</code>).</p>
-
-<pre>
+Title: Verifying Apache HTTP Server Releases
+Notice: 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.
+
+All official releases of code distributed by the Apache HTTP Server Project
+are signed by the release manager for the release. PGP signatures and MD5
+hashes are available along with the distribution.
+
+You should download the PGP signatures and MD5 hashes directly from the
+Apache Software Foundation rather than our mirrors. This is to help ensure
+the integrity of the signature files. However, you are encouraged to
+download the releases from our mirrors. (Our download page points you at
+the mirrors for the release and the official site for the signatures, so
+this happens automatically for you.)
+
+# Checking Signatures # {#Checking}
+
+The following example details how signature interaction works. In this
+example, you are already assumed to have downloaded `httpd-2.0.44.tar.gz`
+(the release) and `httpd-2.0.44.tar.gz.asc` (the detached signature).
+
+This example uses [The GNU Privacy Guard](http://www.gnupg.org/). Any
+[OpenPGP](http://www.openpgp.org/) -compliant program should work
+successfully.
+
+First, we will check the detached signature ( `httpd-2.0.44.tar.gz.asc` )
+against our release ( `httpd-2.0.44.tar.gz` ).
+`
% gpg httpd-2.0.44.tar.gz.asc
gpg: Signature made Sat Jan 18 07:21:28 2003 PST using DSA key ID DE885DD3
gpg: Can't check signature: public key not found
-</pre>
-
-<p>We don't have the release manager's public key (<code>DE885DD3</code>) in
-our local system. You now need to retrieve the public key from a key
-server. One popular server is <code>pgpkeys.mit.edu</code> (which has a <a
-href="http://pgp.mit.edu/">web interface</a>). The public key servers are
-linked together, so you should be able to connect to any key server.</p>
-
-<pre>
+`
+We don't have the release manager's public key ( `DE885DD3` ) in our local
+system. You now need to retrieve the public key from a key server. One
+popular server is `pgpkeys.mit.edu` (which has a [web
+interface](http://pgp.mit.edu/) ). The public key servers are linked
+together, so you should be able to connect to any key server.
+`
% gpg --keyserver pgpkeys.mit.edu --recv-key DE885DD3
gpg: requesting key DE885DD3 from HKP keyserver pgpkeys.mit.edu
gpg: trustdb created
-gpg: key DE885DD3: public key "Sander Striker <striker@apache.org>" imported
+gpg: key DE885DD3: public key "Sander Striker <striker@apache.org>"
+imported
gpg: Total number processed: 1
-gpg: imported: 1
-</pre>
-
-<p>In this example, you have now received a public key for an entity known
-as 'Sander Striker <striker@apache.org>' However, you have no way
-of verifying this key was created by the person known as Sander Striker.
-But, let's try to verify the release signature again.</p>
-
-<pre>
+gpg: imported: 1
+`
+In this example, you have now received a public key for an entity known as
+'Sander Striker <striker@apache.org>' However, you have no way of
+verifying this key was created by the person known as Sander Striker. But,
+let's try to verify the release signature again.
+`
% gpg httpd-2.0.44.tar.gz.asc
gpg: Signature made Sat Jan 18 07:21:28 2003 PST using DSA key ID DE885DD3
gpg: Good signature from "Sander Striker <striker@apache.org>"
-gpg: aka "Sander Striker <striker@striker.nl>"
+gpg: aka "Sander Striker <striker@striker.nl>"
gpg: checking the trustdb
gpg: no ultimately trusted keys found
gpg: WARNING: This key is not certified with a trusted signature!
-gpg: There is no indication that the signature belongs to the owner.
+gpg: There is no indication that the signature belongs to the
+owner.
Fingerprint: 4C1E ADAD B4EF 5007 579C 919C 6635 B6C0 DE88 5DD3
-</pre>
-
-<p>At this point, the signature is good, but we don't trust this key. A good
-signature means that the file has not been tampered. However, due to the
+`
+At this point, the signature is good, but we don't trust this key. A good
+signature means that the file has not been tampered. However, due to the
nature of public key cryptography, you need to additionally verify that key
-DE885DD3 was created by the <b>real</b> Sander Striker.</p>
-
-<p>Any attacker can create a public key and upload it to the public key
-servers. They can then create a malicious release signed by this fake key.
-Then, if you tried to verify the signature of this corrupt release, it would
-succeed because the key was not the 'real' key. Therefore, you need to
-validate the authenticity of this key.</p>
-
-</section>
-
-<section id="Validating">
-<title>Validating Authenticity of a Key</title>
-
-<p>You may download <a href="http://www.apache.org/dist/httpd/KEYS">public keys
-for the Apache HTTP Server developers</a> from our website or retrieve them off
-the public PGP keyservers (see above). However, importing these keys is not
-enough to verify the integrity of the signatures. If a release verifies as
-good, you need to validate that the key was created by an official
-representative of the Apache HTTP Server Project.</p>
-
-<p>The crucial step to validation is to confirm the key fingerprint of the
-public key.</p>
+DE885DD3 was created by the **real** Sander Striker.
-<pre>
+Any attacker can create a public key and upload it to the public key
+servers. They can then create a malicious release signed by this fake key.
+Then, if you tried to verify the signature of this corrupt release, it
+would succeed because the key was not the 'real' key. Therefore, you need
+to validate the authenticity of this key.
+
+# Validating Authenticity of a Key # {#Validating}
+
+You may download [public keys for the Apache HTTP Server
+developers](http://www.apache.org/dist/httpd/KEYS) from our website or
+retrieve them off the public PGP keyservers (see above). However, importing
+these keys is not enough to verify the integrity of the signatures. If a
+release verifies as good, you need to validate that the key was created by
+an official representative of the Apache HTTP Server Project.
+
+The crucial step to validation is to confirm the key fingerprint of the
+public key.
+`
% gpg --fingerprint DE885DD3
pub 1024D/DE885DD3 2002-04-10 Sander Striker <striker@apache.org>
Key fingerprint = 4C1E ADAD B4EF 5007 579C 919C 6635 B6C0 DE88 5DD3
-uid Sander Striker <striker@striker.nl>
+uid Sander Striker <striker@striker.nl>
sub 2048g/532D14CA 2002-04-10
-</pre>
+`
+A good start to validating a key is by face-to-face communication with
+multiple government-issued photo identification confirmations. However,
+each person is free to have their own standards for determining the
+authenticity of a key. Some people are satisfied by reading the key
+signature over a telephone (voice verification). For more information on
+determining what level of trust works best for you, please read the GNU
+Privacy Handbook section on [Validating other keys on your public
+keyring](http://www.gnupg.org/gph/en/manual.html#AEN335).
-<p>A good start to validating a key is by face-to-face communication with
-multiple government-issued photo identification confirmations. However, each
-person is free to have their own standards for determining the authenticity of
-a key. Some people are satisfied by reading the key signature over a telephone
-(voice verification). For more information on determining what level of trust
-works best for you, please read the GNU Privacy Handbook section on <a
-href="http://www.gnupg.org/gph/en/manual.html#AEN335">Validating other keys on
-your public keyring</a>.</p>
-
-<p>Most of the Apache HTTP Server developers have attempted to sign each
-others' keys (usually with face-to-face validation). Therefore, in order to
+Most of the Apache HTTP Server developers have attempted to sign each
+others' keys (usually with face-to-face validation). Therefore, in order to
enter the web of trust, you should only need to validate one person in our
-web of trust. (Hint: all of our developers' keys are in the KEYS file.)</p>
-
-<p>For example, the following people have signed the public key for Sander
-Striker. If you verify any key on this list, you will have a trust
-path to the DE885DD3 key. If you verify a key that verifies one of the
-signatories for DE885DD3, then you will have a trust path. (So on, and so
-on.)</p>
+web of trust. (Hint: all of our developers' keys are in the KEYS file.)
-<pre>
+For example, the following people have signed the public key for Sander
+Striker. If you verify any key on this list, you will have a trust path to
+the DE885DD3 key. If you verify a key that verifies one of the signatories
+for DE885DD3, then you will have a trust path. (So on, and so on.)
+`
pub 1024D/DE885DD3 2002-04-10 Sander Striker <striker@apache.org>
-sig E2226795 2002-05-01 Justin R. Erenkrantz
-sig 3 DE885DD3 2002-04-10 Sander Striker
-sig CD4DF205 2002-05-28 Wolfram Schlich
-sig E005C9CB 2002-11-17 Greg Stein
-sig CC8B0F7E 2002-11-18 Aaron Bannert
-sig DFEAC4B9 2002-11-19 David N. Welton
-sig 2 82AB7BD1 2002-11-17 Cliff Woolley
-sig 2 13046155 2002-11-28 Thom May
-sig 3 19311B00 2002-11-17 Chuck Murcko
-sig 3 F894BE12 2002-11-17 Brian William Fitzpatrick
-sig 3 5C1C3AD7 2002-11-18 David Reid
-sig 3 E04F9A89 2002-11-18 Roy T. Fielding
-sig 3 CC78C893 2002-11-19 Rich Bowen
-sig 3 08C975E5 2002-11-21 Jim Jagielski
-sig 3 F88341D9 2002-11-18 Lars Eilebrecht
-sig 3 187BD68D 2002-11-21 Ben Hyde
-sig 3 49A563D9 2002-11-23 Mark Cox
+sig E2226795 2002-05-01 Justin R. Erenkrantz
+sig 3 DE885DD3 2002-04-10 Sander Striker
+sig CD4DF205 2002-05-28 Wolfram Schlich
+sig E005C9CB 2002-11-17 Greg Stein
+sig CC8B0F7E 2002-11-18 Aaron Bannert
+sig DFEAC4B9 2002-11-19 David N. Welton
+sig 2 82AB7BD1 2002-11-17 Cliff Woolley
+sig 2 13046155 2002-11-28 Thom May
+sig 3 19311B00 2002-11-17 Chuck Murcko
+sig 3 F894BE12 2002-11-17 Brian William Fitzpatrick
+sig 3 5C1C3AD7 2002-11-18 David Reid
+sig 3 E04F9A89 2002-11-18 Roy T. Fielding
+sig 3 CC78C893 2002-11-19 Rich Bowen
+sig 3 08C975E5 2002-11-21 Jim Jagielski
+sig 3 F88341D9 2002-11-18 Lars Eilebrecht
+sig 3 187BD68D 2002-11-21 Ben Hyde
+sig 3 49A563D9 2002-11-23 Mark Cox
...more signatures redacted...
-</pre>
-
-<p>Since the developers are usually quite busy, you may not immediately find
+`
+Since the developers are usually quite busy, you may not immediately find
success in someone who is willing to meet face-to-face (they may not even
-respond to your emails because they are so busy!). If you do not have a
+respond to your emails because they are so busy!). If you do not have a
developer nearby or have trouble locating a suitable person, please send an
-email to the address of the key you are attempting to verify. They may be able
-to find someone who will be willing to validate their key or arrange alternate
-mechanisms for validation.</p>
-
-<p>Once you have entered the web of trust, you should see the following upon
-verifying the signature of a release.</p>
-
-<pre>
+email to the address of the key you are attempting to verify. They may be
+able to find someone who will be willing to validate their key or arrange
+alternate mechanisms for validation.
+
+Once you have entered the web of trust, you should see the following upon
+verifying the signature of a release.
+`
% gpg httpd-2.0.44.tar.gz.asc
gpg: Signature made Sat Jan 18 07:21:28 2003 PST using DSA key ID DE885DD3
gpg: Good signature from "Sander Striker <striker@apache.org>"
-gpg: aka "Sander Striker <striker@striker.nl>"
-</pre>
-
-</section>
-
-</body>
-</document>
+gpg: aka "Sander Striker <striker@striker.nl>"
+`