This is an automated email from the ASF dual-hosted git repository. rcordier pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/james-project.git
commit 0b195a92265d1d7f345cc911d9970f32f680d0dc Author: Rene Cordier <rcord...@linagora.com> AuthorDate: Thu Aug 20 16:11:07 2020 +0700 JAMES-3187 Contributing subsection of the community new documentation --- docs/modules/community/pages/contributing.adoc | 184 ++++++++++++++++++++++++- docs/modules/community/pages/guidelines.adoc | 3 +- 2 files changed, 185 insertions(+), 2 deletions(-) diff --git a/docs/modules/community/pages/contributing.adoc b/docs/modules/community/pages/contributing.adoc index 463288d..7691e4e 100644 --- a/docs/modules/community/pages/contributing.adoc +++ b/docs/modules/community/pages/contributing.adoc @@ -1,3 +1,185 @@ = Contributing -(TODO) +This document defines the different ways available for contributing to the Apache James project. + +To keep you informed on James issues, subscribe to the relevant xref:mailing-lists.adoc[mailing lists]. + +== Be involved in the community + +An easy start is to be involved in the community. + +Share your experiences with James, your needs, your enhancements proposition via the +xref:mailing-lists.adoc[mailing lists], on https://gitter.im/apache/james-project[Gitter], or on our +https://issues.apache.org/jira/projects/JAMES/issues[Bug Tracker]. + +Don't hesitate to write articles and blog posts. Use your preferred media to spread the love! + +== Reporting bugs + +Many improvements come as a direct result of bug reports. + +To report a bug, please use the appropriate Bug Tracker JIRA link according to the project you want to address: + +* https://issues.apache.org/jira/browse/JAMES[Server] +* https://issues.apache.org/jira/browse/MAILET[Mailet] +* https://issues.apache.org/jira/browse/MAILBOX[Mailbox] +* https://issues.apache.org/jira/browse/PROTOCOLS[Protocols] +* https://issues.apache.org/jira/browse/MPT[MPT] +* https://issues.apache.org/jira/browse/MIME4J[Mime4j] +* https://issues.apache.org/jira/browse/JSIEVE[jSieve] +* https://issues.apache.org/jira/browse/JSPF[jSPF] +* https://issues.apache.org/jira/browse/JDKIM[jDKIM] +* https://issues.apache.org/jira/browse/HUPA[Hupa] + +Once you are logged on the appropriate JIRA page, click on the red Create button, then complete the different fields +as accurately as possible, so that any user can reproduce the reported bug. Also note that all your information must be +readable (use markdown). + +Then, you have to click on Create to submit your bug. + +=== Reporting security vulnerabilities + +http://www.apache.org/security/[Security vulnerabilities] should be announced to the Apache Security team. +PMCs will be notified about them, and will work hard to propose fixes as fast as possible. + +Specific details about security in James can be found here. + +== Documentation + +Documentation is an easy way to get on board! Check out the +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] +label on JIRA to get some ideas. +Report on JIRA the typos you spot, the information you miss, and any improvement you can think of. +The next step is to contribute the documentation changes via https://github.com/apache/james-project/tree/master/docs/modules[Git]. + +To edit an existing document try to edit the adoc version in `docs/modules` (check it out from Git) and if you can, submit a +patch as for xref:_code_patches[Code Patches]. + +If you want to contribute new files please try to use the AsciiDoc format as shown in `docs/modules`. + +If all this seems like unnecessary nonsense, send us whatever you like, we'd still be happy to receive good documentation. + +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 https://git-wip-us.apache.org/repos/asf/james-site.git[site module] +which will be automatically published via gitpubsub to http://james.apache.org[Apache James web site]. + +== How to contribute some code? + +* Clone the source code of the project from its link:git://git.apache.org/james-project.git[apache git repository] or its +https://github.com/apache/james-project[Github] +* 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. + +Alternatively you can create a patch as xref:_code_patches[outlined below], and attach it to the JIRA ticket. + +A valid commit comment might be: + +``` +JAMES-2285 My awesome commit title + +Here is some more details about what my commit does, and the rationals of the choice I took. +``` + +=== Licenses + +All contributions to the James project are made under the https://www.apache.org/licenses[Apache license 2.0] + +=== Contributions proposals + +* We reference some easy tasks to start with: +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] +* We have a collection of minor fixes awaiting contributions: +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] +* Challenge yourself with some cool features we thought to: +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] + +Additional ideas are more than welcome. Don't hesitate to discuss that with us! + +=== Coding standards + +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. + +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 +https://www.oracle.com/java/technologies/javase/codeconventions-contents.html[Java Coding Conventions]. + +*Developers who commit code that does not follow the coding conventions outlined in this document will be responsible +for fixing their own code.* + +. Your code should pass our https://github.com/apache/james-project/blob/master/checkstyle.xml[checkstyle] which runs +upon mvn clean install. +. Extra spaces between parentheses are not allowed: + +``` + if (foo) > Good + + or + + if ( foo ) > Bad +``` + +[start=3] +. Four spaces. *No tabs.* Period. +The James mailing list receives commit messages that are almost impossible to read if tabs are used. +. Use Unix linefeeds for all .java source code files. Only platform-specific files (e.g. .bat files for Windows) should +contain non-Unix linefeeds. +. Javadoc *MUST* 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. +. The standard Apache license header *MUST* be placed at the top of every file. +. Your change set *MUST* be covered by tests. We also strongly appreciate integration tests. +. We also require the following best practice regarding maven and the *pom.xml*: + +** Define your dependency versions in james-project pom.xml. This structurally ensures all projects get the same v +ersion, and that there is no version clashes. +** Don't use _org.apache.james_ groupId for your dependencies. Use _${james.groupId}_. If not, you break the policies +for automatic sorting, as well as make it more ambiguous. +** You should be ordering your dependencies. The sort order is: +*** If the project is part of org.james.apache groupId? Internal dependencies goes first. +*** Then we order by groupId +*** Then we order by artifactId +*** Then we order by type. test-jar goes last. + +You should also split multiple attributes each on a new line. + +You should ensure your POM files, as well as sections ordering follow the +https://maven.apache.org/ref/3.0.3/maven-model/maven.html[Maven Model]. + +=== Code patches + +Patches should be attached to the corresponding JIRA issue. + +Always use diff -u to generate patches, so we can apply them using 'patch'. + +Make sure the patch only contains what is intended, your checkout could be outdated. + +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. + +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. + +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. + +== Idea or design proposals + +People can submit ideas, features or design changes proposals by discussing it through the +xref:mailing-lists.adoc[mailing lists] and/or submitting an ADR (Architecture Decision Record). A discussion +on the mailing list getting a consensus of the community can be the object of the writing of an ADR to confirm the +change agreed upon. + +ADRs *MUST* be submitted under the folder `src/adr` via a pull request. The standards used for writing an ADR are +described in the https://github.com/apache/james-project/blob/master/src/adr/0001-record-architecture-decisions.md[first ADR] +written for the Apache James project. + +The number of the ADR should be incremental. If an other ADR gets merged concurrently, the committer is responsible for +updating its number accordingly. + +When the ADR reaches a consensus within the community and is accepted, it can be merged and goes into effect. + +An ADR can't be removed after being accepted and merged. However, a new ADR can supersede a previous one. This is so +we are able to keep track on all the decisions being made regarding the project. diff --git a/docs/modules/community/pages/guidelines.adoc b/docs/modules/community/pages/guidelines.adoc index e07f1a7..cd31b8c 100644 --- a/docs/modules/community/pages/guidelines.adoc +++ b/docs/modules/community/pages/guidelines.adoc @@ -127,7 +127,8 @@ categories corresponding to the change status: * *Concept/Plan* An idea or plan for a change. These are represented as ADRs (Architectural Decision Records), stored under the `src/adr` -folder. Votes are being requested early so as to uncover conflicts before too much work is done. +folder. Votes are being requested early so as to uncover conflicts before too much work is done. You can find more +information about this xref:contributing.adoc#_idea_or_design_proposals[here]. * *Proposed Patch* A specific set of changes to the current product in the form of input to the patch command (a diff output). --------------------------------------------------------------------- To unsubscribe, e-mail: server-dev-unsubscr...@james.apache.org For additional commands, e-mail: server-dev-h...@james.apache.org