Repository: incubator-samoa Updated Branches: refs/heads/master 2c7a1704b -> e421433a5
SAMOA-13: Update "How to contribute" guidelines Fix #6 Project: http://git-wip-us.apache.org/repos/asf/incubator-samoa/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-samoa/commit/e421433a Tree: http://git-wip-us.apache.org/repos/asf/incubator-samoa/tree/e421433a Diff: http://git-wip-us.apache.org/repos/asf/incubator-samoa/diff/e421433a Branch: refs/heads/master Commit: e421433a5390dc70a818019bbe7710a52fb7e253 Parents: 2c7a170 Author: Gianmarco De Francisci Morales <[email protected]> Authored: Tue Apr 7 11:20:53 2015 +0300 Committer: Gianmarco De Francisci Morales <[email protected]> Committed: Tue Apr 7 11:20:53 2015 +0300 ---------------------------------------------------------------------- CONTRIBUTING.md | 63 +++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 55 insertions(+), 8 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-samoa/blob/e421433a/CONTRIBUTING.md ---------------------------------------------------------------------- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 789e63d..7ed0b44 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,18 +1,65 @@ How to contribute? ================= -User contribution is essential to keep moving the project forward. +The best way to submit a contribution to Apache SAMOA is through a GitHub pull request. -# Getting Started +Here is a guide to contribute to Apache SAMOA. -1. [Fork the repository](https://help.github.com/articles/fork-a-repo) on GitHub +## Where is the source code? -2. Sign the [Contributor License Agreement] (http://www.clahub.com/agreements/gdfm/samoa) +SAMOA source code is maintained through **git**. The Apache SAMOA [git repository](git://git.apache.org/incubator-samoa.git) is the source of truth. Only SAMOA committers can push updates to this repo. -3. Create a feature branch ```git checkout -b branch_name``` +The Apache git repo is [mirrored to github](https://github.com/apache/incubator-samoa) for convenience. This mirror is read-only. -4. Make your changes (please make commits that are logical units) +For writing contributions we suggest you start by [forking](https://help.github.com/articles/fork-a-repo) the [GitHub Apache SAMOA](https://github.com/apache/incubator-samoa) repository. -5. Build and run tests +## How do I build the software? -6. Submit a [pull request](https://help.github.com/articles/using-pull-requests) +We use [**maven**](http://maven.apache.org/): `mvn clean package`. + +Note that this only builds the core artifacts of SAMOA (instances, API, local engine and test framework). + +To build everything, including the integrations with various stream processing platforms use the "all" profile: `mvn clean package -Pall`. + +You may also specify platform profiles individually: `-Pstorm`, `-Ps4`, `-Psamza`, `-Pthreads`. + +## What rules should I follow in a code contribution? + +### Coding convention + +* All public classes and methods should have informative Javadoc comments. +* Do not use @author tags. +* Code should be formatted according to [Sun's conventions](http://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html), with the following exceptions: + * **Use spaces for indentation, not tabs**. + * **Indent two (2) spaces per level, not four (4)**. + * **Line length limit is 120 chars, instead of 80 chars**. +* SAMOA includes an [eclipse-format.xml](https://github.com/apache/incubator-samoa/blob/master/eclipse-format.xml) formatting template that Eclipse or IntelliJ idea users might find convenient. +* Prefer qualified imports to wildcard imports. + +### Tests + +* Contributions should pass existing unit tests (`mvn test -Pall`). +* New unit tests should be provided to demonstrate bugs and fixes. JUnit 4 is our test framework. + +### Organization of the code changes + +The most natural way is to: + +1. Create a new feature branch in your local git repo, e.g. using a JIRA ticket ID as the branch name. +2. Make code changes and separate the commits into logical units. +3. Submit a pull request from that feature branch. + +## How do I submit a contribution? + +Once you have a contribution that follows the coding convention, passes the tests, and is organized into logical commits, you may submit a pull request. + +The recommended way is to submit a pull request **through GitHub**. + +1. Get a JIRA reference: + 1. If your contribution has no JIRA ticket, create a new JIRA ticket, describing the issue (see [^1] for how to do this). + 2. Otherwise note the existing JIRA ticket ID ( e.g. `SAMOA-XX` ) +1. Create a pull request from your contribution, and submit it through the github interface to the github SAMOA mirror repo. Make sure to **include the JIRA ticket ID in the description of the pull request**, so that the JIRA ticket is automatically updated. e.g.: `SAMOA-XX: Fixes XYZ` + +The patch will be reviewed and voted upon, according to the [project's bylaws](http://samoa.incubator.apache.org/documentation/Bylaws.html). + +[^1]: You need to be logged into ASF's JIRA and use the create button on [SAMOA's JIRA page](https://issues.apache.org/jira/browse/SAMOA/).
