You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by bt...@apache.org on 2018/02/01 10:44:43 UTC
[10/20] james-project git commit: JAMES-2315 Propose some related
improvements to the contribute.xml document
JAMES-2315 Propose some related improvements to the contribute.xml document
We should re-use main page "Contribute" information.
- Introduction of contribution suggestions
- Add Security section
- Add "Be involved in the community" section
- Reorder section:
- Code patches should come last as we don't really want people to do that.
- Put documentation before contributing code. That emphasis the fact that we do care about non-coding contributions.
Light "Coding standard" enhancements:
- Speak about test.
- Mention the newly introduced checkstyle.
Project: http://git-wip-us.apache.org/repos/asf/james-project/repo
Commit: http://git-wip-us.apache.org/repos/asf/james-project/commit/81382bc0
Tree: http://git-wip-us.apache.org/repos/asf/james-project/tree/81382bc0
Diff: http://git-wip-us.apache.org/repos/asf/james-project/diff/81382bc0
Branch: refs/heads/master
Commit: 81382bc04f706f9d7396b1aedba0fbe638f8565f
Parents: f409e0d
Author: benwa <bt...@linagora.com>
Authored: Tue Jan 30 16:27:47 2018 +0700
Committer: benwa <bt...@linagora.com>
Committed: Thu Feb 1 17:35:51 2018 +0700
----------------------------------------------------------------------
src/homepage/index.html | 17 ++-
src/site/xdoc/contribute.xml | 238 ++++++++++++++++++++------------------
2 files changed, 135 insertions(+), 120 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/james-project/blob/81382bc0/src/homepage/index.html
----------------------------------------------------------------------
diff --git a/src/homepage/index.html b/src/homepage/index.html
index a45d902..a105762 100644
--- a/src/homepage/index.html
+++ b/src/homepage/index.html
@@ -201,16 +201,16 @@ WHAT WILL YOU TRY:</b><br>
<section>
<p class="align-left">
James is a project that lives from the contributions of its community.<br/>
- <b>Anyone can contribute!</b> That's right, we always want to hear from people with contributions to the code, the documentation, the website, and bug reports. <br>
+ <b>Anyone can contribute!</b> That's right, we always want to hear from people with contributions to the code, the documentation, the website, and bug reports.
We more than welcome non-coding contributions.<br>
- Here are the different ways of contributing:
+ Here are different ways to contribute:
</p>
<ul class="no-padding no-margin">
<li class="post-template center-icon">
<a href="http://www.apache.org/licenses/"><span class="icon fa-copyright "></span></a>
<span class="details">
<b>Licenses:</b>
- <br/>All contributions to the James project are made under the <a class="comm" alt="License" href="http://www.apache.org/licenses/">Apache license 2.0</a><br/>
+ <br/>All contributions to the James project are made under the <a class="comm" alt="License" href="http://www.apache.org/licenses/">Apache license 2.0</a>
</span>
</li>
<li class="post-template center-icon">
@@ -241,10 +241,9 @@ WHAT WILL YOU TRY:</b><br>
<span class="details">
<b>How to contribute code changes:</b>
<br/>Read our sources from the <a href="git://git.apache.org/james-project.git" class="comm" alt="James Git sources">Apache Git</a>.<br/>
- You can also come and interact with us on <a href="https://github.com/apache/james-project" class="comm" alt="James on GitHub">GitHub</a>.<br/>
- On <a href="https://github.com/apache/james-project" class="comm" alt="James on GitHub">GitHub</a> you can share your work by creating a pull request.<br/>
- Alternatively, you can attach a patch to the JIRA issue.<br/>
- After a review, and exchanges with you, a Apache James developer will integrate the changes to the code base once it matches our policies.
+ You can also come and interact with us on <a href="https://github.com/apache/james-project" class="comm" alt="James on GitHub">GitHub</a> and share your work by creating a pull request.<br/>
+ Alternatively, you can attach a <a class="comm" alt="Patch" href="http://james.apache.org/contribute.html#Code_Patches">patch</a> to the JIRA issue.<br/>
+ After a review, and exchanges with you, an Apache James developer will integrate the changes once it matches our policies.
</span>
</li>
@@ -276,8 +275,7 @@ WHAT WILL YOU TRY:</b><br>
<b>Additional information:</b><br/>
The <a class="comm" alt="More details about contributing" href="http://james.apache.org/contribute.html">contribute</a> page contains more details about the various details exposed above.<br/>
To match the quality expectations of our community, we enforce <a class="comm" alt="Coding Standards" href="http://james.apache.org/contribute.html#Coding_Standards">coding standards</a>.<br/>
- We rely on <a class="comm" alt="checkstyle" href="https://github.com/apache/james-project/blob/master/checkstyle.xml">checkstyle</a> for style checking.<br/>
- Amongst other common practices: every file should start with the Apache License, code changes should be covered by tests. . .
+ We rely on <a class="comm" alt="checkstyle" href="https://github.com/apache/james-project/blob/master/checkstyle.xml">checkstyle</a> for style checking.
</span>
</li>
</ul>
@@ -355,6 +353,7 @@ WHAT WILL YOU TRY:</b><br>
<li class="no-padding"><a href="#first">Get Started</a></li>
<li class="no-padding"><a href="#posts">Last Posts</a></li>
<li class="no-padding"><a href="#second">Community</a></li>
+ <li class="no-padding"><a href="#third">Contribute</a></li>
<li class="no-padding"><a href="https://james.apache.org/"><span class="fa fa-external-link"></span> Documentation</a></li>
</ul>
</section>
http://git-wip-us.apache.org/repos/asf/james-project/blob/81382bc0/src/site/xdoc/contribute.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/contribute.xml b/src/site/xdoc/contribute.xml
index 4a89203..25e5a0c 100644
--- a/src/site/xdoc/contribute.xml
+++ b/src/site/xdoc/contribute.xml
@@ -28,7 +28,8 @@
<section name="Introduction">
<p>
- <b>Anyone can contribute</b>
+ James is a project that lives from the contributions of its community.<br/>
+ <b>Anyone can contribute.</b>
<br />
That's right, we always want to hear from people with
contributions to the code,
@@ -45,6 +46,17 @@
</p>
</section>
+ <section name="Be involved in the community">
+ <p>
+ An easy start is to be involved in the community.<br/>
+ Share your experiences with James, your needs, your enhancements proposition via the
+ <a href="https://james.apache.org/mail.html">mailing lists</a>, on <a href="https://gitter.im/apache/james-project">
+ gitter</a>, or on our <a href="https://issues.apache.org/jira/browse/JAMES">Bug Tracker</a>.<br/>
+
+ Don't hesitate to write articles and blog posts. Use your preferred media to spread the love!
+ </p>
+ </section>
+
<section name="Reporting Bugs">
<p>
Many improvements come as a direct result of bug reports.
@@ -81,112 +93,93 @@
<br />
Then, you have to click on Create to submit your bug.
</p>
- </section>
-
- <section name="How to contribute to the code?">
- <p>
- Clone the source code of the project from its
- <a href="https://github.com/apache/james-project">Github</a>
- or its <a href="git://git.apache.org/james-project.git">apache git repository</a>
- <br />
- Create your branch and name it with the JIRA ticket number.
- Create a Pull Request with your branch name
- and prefix its different commits with the same name.
- <br />
- </p>
- </section>
- <section name="Code Patches">
- <p>
- Patches should be attached to the corresponding JIRA issue.
- <br />
- <b>Always</b>
- use diff -u to generate patches, so we can apply them using
- 'patch'.
- <br />
-
- <br />
- Make sure the patch only contains what is intended, your
- checkout could be outdated.
- <br />
- 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 />
- 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 />
- </p>
+ <subsection name="Reporting security vulnerabilities">
+ <a class="comm" alt="Security" href="http://www.apache.org/security/">Security</a>: Vulnerabilities should be announced to the Apache Security team.<br/>
+ PMCs will be notified about them, and will work hard to propose fixes as fast as possible.<br/>
+ Specific details about security in James can be found <a class="comm" alt="security in James" href="http://james.apache.org/server/feature-security.html">here</a>.
- <p>
- The reason for these rules is so that committers can easily see
- what you are trying to achieve,
- it is their responsibility 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 committed quickly.
- <br />
- </p>
+ </subsection>
</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>Documentation is an easy way to get on board!
+
+ Check out the <a class="comm" alt="Documentation" href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20JAMES%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20documentation%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC">~documentation</a> label on JIRA to get some ideas.<br/>
+ Report on JIRA the typo you spots, the information you miss, and any improvement you can think to.<br/>
+ The next step is to contribute the documentation changes via <a class="comm" alt="The website on github" href="https://github.com/apache/james-project/tree/master/src/site/xdoc">Git</a>.
</p>
<p>
- To edit an existing document try to edit the xml version in src/site/xdocs
- (check it out from GIT)
- and if you can, submit a patch as for Code Patches.
+ To edit an existing document try to edit the xml version in <code>src/site/xdoc</code>
+ (check it out from GIT) 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.
+ If you want to contribute new files please try to use the markdown format as
+ shown in <code>src/site/markdown</code>.
</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.
+ text documents without any styling, so that we can get at the words
+ and easily convert them into the right format.
</p>
<p>
If all this seems like unnecessary nonsense, send us whatever you
- like, we'd still be
- happy to receive good documentation.
+ 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://git-wip-us.apache.org/repos/asf/james-site.git">
- site module
- </a>
+ maintained with the automated build. Once a build is done,
+ the documentation can be further committed in the
+ <a href="https://git-wip-us.apache.org/repos/asf/james-site.git">site module</a>
which will be automatically published via gitpubsub
- to
- <a href="http://james.apache.org">Apache James web site</a>
- .
+ 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.
- .
+ 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="How to contribute to the code?">
+ <p>
+ Clone the source code of the project from its
+ <a href="git://git.apache.org/james-project.git">apache git repository</a>
+ or its <a href="https://github.com/apache/james-project">Github</a>
+ <br />
+ Create your branch and name it with the JIRA ticket number.<br />
+ Create a Pull Request with your branch name and prefix its different commits with the same name.
+ <br />
+ </p>
+
+ <p>Alternatively you can create a patch as <a href="#Code_Patches">outlined below</a>, and attach it to the JIRA ticket.</p>
+ <p>A valid commit comment might be:</p>
+
+ <pre><code>JAMES-2285 My awesome commit title
+
+Here is some more details about what my commit does, and the rationals of the choice I took.</code></pre>
+
+ <subsection name="Contribution proposals">
+ <p>
+ We reference some easy tasks to start with :
+ <a class="comm" alt="Newbie tasks" href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20JAMES%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20newbie%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC">~newbie</a>
+ <br/> We have a collection of minor fixes awaiting contributions:
+ <a class="comm" alt="Easy fixes" href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20JAMES%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20easyfix%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC">~easyfix</a>
+ <br/> Challenge yourself with some cool features we thought to:
+ <a class="comm" alt="Cool features" href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20JAMES%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20feature%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC">~feature</a>
+ <br/>Additional ideas are more than welcome. Don't hesitate to discuss that with us!
+ </p>
+ </subsection>
+ </section>
+
<section name="Coding Standards">
<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>
Submissions to the James project must follow the coding
- conventions
- outlined in this document. James developers
+ 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
@@ -205,28 +198,26 @@
</strong>
</p>
<p>
- 1. Spaces between parentheses are optional. The preference is
- to exclude
- extra spaces. Both of these conventions are
- acceptable:
+ 1. Your code should pass our <a href="https://github.com/apache/james-project/blob/master/checkstyle.xml">checkstyle</a>
+ which runs upon <code>mvn clean install</code>.
+ </p>
+ <p>
+ 2. Extra spaces between parentheses are not allowed:
</p>
<p>
<source><![CDATA[
- if (foo)
+ if (foo) > Good
or
- if ( foo )
+ if ( foo ) > Bad
]]></source>
</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.
+ 3. Four spaces.<strong>NO tabs</strong>. Period. <br/>
+ The James mailing list receives commit messages that
+ are almost impossible to read if tabs are used.
</p>
<p>
In Emacs-speak, this translates to the following command:
@@ -234,29 +225,19 @@
(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
+ 4. 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>5. Javadoc <strong>MUST</strong>
+ exist on all API 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>6. The standard Apache license header <strong>MUST</strong> be placed at the top of every file.</p>
+ <p>7. Your change set <strong>MUST</strong> be covered by tests. We also strongly appreciate integration tests.</p>
<p>
- 6.
- <strong>pom.xml</strong>
+ 8. <strong>pom.xml</strong>
<br/>
We also require the following best practice regarding maven:
@@ -292,6 +273,41 @@
</p>
</section>
+ <section name="Code Patches">
+ <p>
+ Patches should be attached to the corresponding JIRA issue.
+ <br />
+ <b>Always</b>
+ use diff -u to generate patches, so we can apply them using
+ 'patch'.
+ <br />
+
+ <br />
+ Make sure the patch only contains what is intended, your
+ checkout could be outdated.
+ <br />
+ 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 />
+ 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 />
+ </p>
+
+ <p>
+ The reason for these rules is so that committers can easily see
+ what you are trying to achieve,
+ it is their responsibility 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 committed quickly.
+ <br />
+ </p>
+ </section>
+
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org