Author: eric
Date: Thu Apr 19 07:13:52 2012
New Revision: 1327846
URL: http://svn.apache.org/viewvc?rev=1327846&view=rev
Log:
Add information on documentation + format
Modified:
james/project/trunk/src/site/xdoc/contribute.xml
Modified: james/project/trunk/src/site/xdoc/contribute.xml
URL:
http://svn.apache.org/viewvc/james/project/trunk/src/site/xdoc/contribute.xml?rev=1327846&r1=1327845&r2=1327846&view=diff
==============================================================================
--- james/project/trunk/src/site/xdoc/contribute.xml (original)
+++ james/project/trunk/src/site/xdoc/contribute.xml Thu Apr 19 07:13:52 2012
@@ -1,4 +1,4 @@
-<?xml version="1.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
@@ -18,122 +18,217 @@
under the License.
-->
<document>
- <properties>
- <title>Contributors How To</title>
- <author email="[email protected]">Danny Angus</author>
- </properties>
- <body>
- <section name="Introduction">
- <p>
- <b>Anyone can contribute</b><br/>
- That's right, we always want to hear from people with contributions
to the code,
- the documentation, the website, and bug reports.<br/>
- The rest of this document outlines the way to go about these to
maximum effect.<br/>
- </p>
- <p>
- If you are new to this you may be interested in some of these
resources.<br/>
- <a href="http://jakarta.apache.org/site/guidelines.html";>A good,
full, summary of links to guidelines</a><br/>
- Subscribe to the relevant mailing lists (link on the left).<br/>
- <a href="http://jakarta.apache.org/site/contributing.html";>Craig R.
McClanahan's advice how to get involved</a><br/>
- </p>
-
- </section>
-
- <section name="Code Patches">
- <p>
- Patches should be submitted to the developers mailing list.<br/>
- <b>Always</b> use diff -u to generate patches, so we can apply
them using 'patch'.<br/>
+
+ <properties>
+ <title>Contributors How To</title>
+ <author email="[email protected]">James Project Web Team</author>
+ </properties>
+
+ <body>
+
+ <section name="Introduction">
+ <p>
+ <b>Anyone can contribute</b>
+ <br />
+ That's right, we always want to hear from people with
+ contributions to the code,
+ the documentation, the website, and bug reports.
+ <br />
+ The rest of this document outlines the way to go about these to
+ maximum effect.
+ <br />
+ </p>
+ <p>
+ If you are new to this you may be interested in some of these
+ resources.
+ <br />
+ <a href="http://jakarta.apache.org/site/guidelines.html";>A good, full,
summary of links to guidelines</a>
+ <br />
+ Subscribe to the relevant mailing lists (link on the left).
+ <br />
+ <a href="http://jakarta.apache.org/site/contributing.html";>Craig R.
McClanahan's advice how to get involved</a>
+ <br />
+ </p>
+ </section>
+
+ <section name="Code Patches">
+ <p>
+ Patches should be submitted to the developers mailing list.
+ <br />
+ <b>Always</b>
+ use diff -u to generate patches, so we can apply them using
+ 'patch'.
+ <br />
+<!--
+// Update this for SVN
Make sure you are patching the latest cvs (the HEAD).
- (You might want to try 'cvs diff -u -w -b -rHEAD' against the checked
out module where
- you have implemented the patch.<br/>
- <br/>Make sure the patch only contains what is intended, your
checkout could be outdated.<br/>
- Make your patch from the jakarta-james directory and make sure it
conforms
- to the code standards, otherwise it may be ignored. It is OK to
make a single patch covering several
- files, but please only one issue at a time.<br/>
- Prefix the mail subject with [PATCH]<br/>
- Briefly outline the reason for your patch,
- the solution your patch implements, why a patch is
- needed and why your code will solve the problem. Note any bug
numbers your patch addresses.<br/>
- Submit the patch as an attachment to the mail, this
- mail should preferably be in either BASE64 or QuotedPrintable format,
to prevent line wrapping.<br/>
- </p>
-
- <p>
- The reason for these rules is so that commiters can easily see
what you are trying to achieve,
- it is their resonsibility to manage the code and review
submissions,
- if you make it easy for them to see what you are doing your patch
is more likely to
- be commited quickly (or at all).<br/>
- </p>
- </section>
-
- <section name="Adding New Code">
- <p>
- Like the principles for patch submission, mark your mail [PATCH]
and ensure
- your submission conforms to the code standards. Provide a Brief
outline of
- your intentions, as above, so that your code can be reviewed
easily, and a
- note of any relevant bug numbers.<br/>
- New files must contain a reference to the Apache licence, copy the
header from an existing file.<br/>
- It also helps if you send your files in an archive (tar, zip)
which preserves directories, make it from the jakarta-james directory so we can
un-tar your files into the right place.
- </p>
- </section>
-
- <section name="Reporting and Fixing Bugs">
- <p>
- Many improvements come as a direct result of bug
- reports, and contributed fixes, often by the same person. It is
sometimes said that Apache
- projects evolve because users become so fed-up waiting for bugs to
be addressed that they
- fix them themselves. :)<br/>
- If you report a bug, <a
href="http://issues.apache.org/jira";>here</a> we'd appreciate it if you could
send a mail to the users or developers
- mailing lists, so that we can discuss it with you, bugzilla isn't
a great way for mediating
- communication.<br/>
- If you want to fix a bug, please contribute your changes according
to the guidelines above,
- in the Code Patches section. It is much simpler to deal with
submissions if they all come
- through the same channel. If you still really want to attach
patches to bug submissions, please do send us a mail tagged [PATCH] too, so
that we notice your patch.
- </p>
- </section>
-
- <section name="Documentation">
- <p>
- While we are glad to accept contributions to documentation
- from anyone, in almost any format, because its much better than
none, please consider these
- guidelines to help us to assimilate your contribution.<br/>
- To edit an existing document try to edit the xml version in
src/xdocs (check it out from cvs)
- and if you can, submit a patch as for Code Patches.<br/>
- If you want to contribute new files please try to use the simple
xml format we use.<br/>
- If this means nothing to you please try to contribute HTML or
plain text documents without
- any styling, so that we can get at the words and easily convert
them into our xml format.<br/>
- If all this seems like unnecessary nonsense, send us whatever you
like, we'd still be
- happy to receive good documentation.
- </p>
- </section>
-
- <section name="Coding Standards">
-
- <p>
- Submissions to the James project must follow the coding conventions
- outlined in this document. James developers
- are asked to follow coding conventions already present in the code.
- (For example, if the existing code has the bracket on
- the same line as the if statement, then all subsequent code
- should also follow that convention.) Anything not
- explicitly mentioned in this document should adhere to the
- official
- <a
href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html";>Sun
- Java Coding Conventions</a>.
- </p>
-
- <p>
- <strong>Developers who commit code that does not follow
- the coding conventions outlined in this document will be
- responsible for fixing their own code.</strong>
- </p>
-
- <p>
- 1. Spaces between parentheses are optional. The preference is to
exclude
- extra spaces. Both of these conventions are acceptable:
- </p>
-
- <p>
+ (You might
+ want to try 'cvs diff -u -w -b -rHEAD' against the checked out
+ module where
+ you have implemented the patch.
+ <br />
+-->
+ <br />
+ Make sure the patch only contains what is intended, your
+ checkout could be outdated.
+ <br />
+ Make your patch from the jakarta-james directory and make sure
+ it conforms
+ to the code standards, otherwise it may be ignored. It is OK to make a
+ single patch covering several
+ files, but please only one issue at a time.
+ <br />
+ Prefix the mail subject with [PATCH]
+ <br />
+ Briefly outline the reason for your patch,
+ the solution your patch implements, why a patch is
+ needed and why your code will solve the problem. Note any bug numbers
your
+ patch addresses.
+ <br />
+ Submit the patch as an attachment to the mail, this
+ mail should
+ preferably be in either BASE64 or QuotedPrintable format, to
+ prevent line wrapping.
+ <br />
+ </p>
+
+ <p>
+ The reason for these rules is so that commiters can easily see
+ what you are trying to achieve,
+ it is their resonsibility to manage the code and review submissions,
+ if you make it easy for them to see what you are doing your
+ patch is more likely to
+ be commited quickly (or at all).
+ <br />
+ </p>
+ </section>
+
+ <section name="Adding New Code">
+ <p>
+ Like the principles for patch submission, mark your mail [PATCH]
+ and ensure
+ your submission conforms to the code standards. Provide a Brief outline
+ of
+ your intentions, as above, so that your code can be reviewed easily,
and
+ a
+ note of any relevant bug numbers.
+ <br />
+ New files must contain a reference to the Apache licence, copy
+ the header from an existing file.
+ <br />
+ It also helps if you send your files in an archive (tar, zip)
+ which preserves directories, make it from the jakarta-james
+ directory so we can un-tar your files into the right place.
+ </p>
+ </section>
+
+ <section name="Reporting and Fixing Bugs">
+ <p>
+ Many improvements come as a direct result of bug
+ reports, and contributed fixes, often by the same person. It is
sometimes
+ said that Apache
+ projects evolve because users become so fed-up waiting for bugs to be
+ addressed that they
+ fix them themselves. :)
+ <br />
+ If you report a bug,
+ <a href="http://issues.apache.org/jira";>here</a>
+ we'd appreciate it if you could send a mail to the users or
+ developers
+ mailing lists, so that we can discuss it with you, bugzilla isn't a
great
+ way for mediating
+ communication.
+ <br />
+ If you want to fix a bug, please contribute your changes
+ according to the guidelines above,
+ in the Code Patches section. It is much simpler to deal with
+ submissions if they all come
+ through the same channel. If you still really want to attach patches
to bug
+ submissions, please do send us a mail tagged [PATCH] too, so
+ that we notice your patch.
+ </p>
+ </section>
+
+ <section name="Documentation">
+ <p>
+ While we are glad to accept contributions to documentation
+ from anyone, in almost any format, because its much better than none,
+ please consider these
+ guidelines to help us to assimilate your contribution.
+ </p>
+ <p>
+ To edit an existing document try to edit the xml version in
src/site/xdocs
+ (check it out from SVN)
+ and if you can, submit a patch as for Code Patches.
+ </p>
+ <p>
+ If you want to contribute new files please try to use the simple xml
+ format we use.
+ </p>
+ <p>
+ If this means nothing to you please try to contribute HTML or plain
+ text documents without
+ any styling, so that we can get at the words and easily convert them
+ into our XML format.
+ </p>
+ <p>
+ If all this seems like unnecessary nonsense, send us whatever you
+ like, we'd still be
+ happy to receive good documentation.
+ </p>
+ <p>
+ Each of the Apache James projects has its own documentation
+ maintained
+ with the automated build. Once a build is done, the documentation can
be
+ further committed in the
+ <a href="https://svn.apache.org/repos/asf/james/site/trunk";>
+ site module
+ </a>
+ which will be automatically published via svnpubsub
+ to
+ <a href="http://james.apache.org";>Apache James web site</a>
+ .
+ </p>
+ <p>
+ Further to this documentation, the
+ <a href="http://wiki.apache.org/james/";>
+ Apache James wiki
+ </a>
+ is available to any and is useful to share any
+ useful documentation.
+ .
+ </p>
+ </section>
+
+ <section name="Coding Standards">
+ <p>
+ Submissions to the James project must follow the coding
+ conventions
+ outlined in this document. James developers
+ are asked to follow coding conventions already present in the code.
+ (For example, if the existing code has the bracket on
+ the same line as the if statement, then all subsequent code
+ should also follow that convention.) Anything not
+ explicitly mentioned in this document should adhere to the
+ official
+ <a
href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html";>Sun
+ Java Coding Conventions
+ </a>
+ .
+ </p>
+ <p>
+ <strong>Developers who commit code that does not follow
+ the coding conventions outlined in this document will be
+ responsible for fixing their own code.
+ </strong>
+ </p>
+ <p>
+ 1. Spaces between parentheses are optional. The preference is
+ to exclude
+ extra spaces. Both of these conventions are
+ acceptable:
+ </p>
+ <p>
<source><![CDATA[
if (foo)
@@ -142,49 +237,63 @@
if ( foo )
]]></source>
- </p>
-
- <p>
- 2. Four spaces. <strong>NO tabs</strong>. Period. The James
- mailing list receives commit messages that are almost impossible
+ </p>
+ <p>
+ 2. Four spaces.
+ <strong>NO tabs</strong>
+ . Period. The James
+ mailing list receives commit messages that
+ are almost impossible
to read if tabs are used.
- </p>
-
- <p>
+ </p>
+ <p>
In Emacs-speak, this translates to the following command:
-
+
(setq-default tab-width 4 indent-tabs-mode nil)
- </p>
-
- <p>
- 3. Use Unix linefeeds for all .java source code files. Only
platform-specific
- files (e.g. .bat files for Windows) should contain non-Unix linefeeds.
- </p>
-
- <p>
- 4. Javadoc <strong>must</strong> exist on all methods. Contributing
- a missing javadoc for any method, class, variable, etc., will be
GREATLY
- appreciated as this will help to improve the James project.
- </p>
-
- <p>
- 5. The standard Apache boilerplace <strong>MUST</strong> be placed
+ </p>
+ <p>
+ 3. Use Unix linefeeds for all .java source code files. Only
+ platform-specific
+ files (e.g. .bat files for Windows) should
+ contain non-Unix linefeeds.
+ </p>
+ <p>
+ 4. Javadoc
+ <strong>must</strong>
+ exist on all methods. Contributing
+ a missing javadoc for any
+ method, class, variable, etc., will be GREATLY
+ appreciated as
+ this will help to improve the James project.
+ </p>
+ <p>
+ 5. The standard Apache boilerplace
+ <strong>MUST</strong>
+ be placed
at the top of every file.
- </p>
-
- <p>
- 6. <strong>pom.xml</strong> files shall follow the same ordering as
seen in the reference
- of the <a
href="http://maven.apache.org/ref/3.0.3/maven-model/maven.html";>Maven Model</a>,
+ </p>
+ <p>
+ 6.
+ <strong>pom.xml</strong>
+ files shall follow the same ordering as seen in the reference
+ of
+ the
+ <a
href="http://maven.apache.org/ref/3.0.3/maven-model/maven.html";>Maven Model</a>
+ ,
split multiple attributes each on a new line.
- </p>
-
- <p>
- <strong>Eclipse IDE</strong><br />
- Eclipse users can import those two files to enfore the code
formating :
- <a href="downloads/formatting.xml">formatting.xml</a> and
- <a href="downloads/codetemplates.xml">codetemplates.xml</a>.
- </p>
- </section>
-
- </body>
- </document>
+ </p>
+ <p>
+ <strong>Eclipse IDE</strong>
+ <br />
+ Eclipse users can import those two files to enfore the code
+ formating :
+ <a href="downloads/formatting.xml">formatting.xml</a>
+ and
+ <a href="downloads/codetemplates.xml">codetemplates.xml</a>
+ .
+ </p>
+ </section>
+
+ </body>
+
+</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
