You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@samoa.apache.org by matthieumorel <gi...@git.apache.org> on 2015/02/02 19:02:26 UTC
[GitHub] incubator-samoa pull request: SAMOA-13: Update "How to contribute"...
GitHub user matthieumorel opened a pull request:
https://github.com/apache/incubator-samoa/pull/6
SAMOA-13: Update "How to contribute" guidelines
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/matthieumorel/incubator-samoa SAMOA-13
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/incubator-samoa/pull/6.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #6
----
commit 77d4845ab472f017b486d82a57c46888b30e4c48
Author: Matthieu Morel <mm...@apache.org>
Date: 2015-02-02T13:24:38Z
Update "How to contribute" guidelines
----
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-samoa pull request: SAMOA-13: Update "How to contribute"...
Posted by matthieumorel <gi...@git.apache.org>.
Github user matthieumorel closed the pull request at:
https://github.com/apache/incubator-samoa/pull/6
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-samoa pull request: SAMOA-13: Update "How to contribute"...
Posted by arinto <gi...@git.apache.org>.
Github user arinto commented on a diff in the pull request:
https://github.com/apache/incubator-samoa/pull/6#discussion_r26012620
--- Diff: CONTRIBUTING.md ---
@@ -1,18 +1,74 @@
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 install`
+
+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 install -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 formatting template that eclipse or intellij idea users might find convenient.
--- End diff --
Probably we can link file `eclipse-format.xml` to the actual file at the head of master branch.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-samoa pull request: SAMOA-13: Update "How to contribute"...
Posted by asfgit <gi...@git.apache.org>.
Github user asfgit closed the pull request at:
https://github.com/apache/incubator-samoa/pull/6
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-samoa pull request: SAMOA-13: Update "How to contribute"...
Posted by gdfm <gi...@git.apache.org>.
Github user gdfm commented on a diff in the pull request:
https://github.com/apache/incubator-samoa/pull/6#discussion_r25952251
--- Diff: CONTRIBUTING.md ---
@@ -1,18 +1,74 @@
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 install`
+
+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 install -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 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`).
--- End diff --
We should add "-Pall" to the "mvn test" command, so that all profiles are tested.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-samoa pull request: SAMOA-13: Update "How to contribute"...
Posted by smarthi <gi...@git.apache.org>.
Github user smarthi commented on a diff in the pull request:
https://github.com/apache/incubator-samoa/pull/6#discussion_r24119311
--- Diff: CONTRIBUTING.md ---
@@ -1,18 +1,73 @@
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 install`
+
+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 install -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, 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 formatting template that eclipse or intellij idea users might find convenient.
+
+### Tests
+
+* Contributions should pass existing unit tests (`mvn test`).
+* New unit tests should be provided to demonstrate bugs and fixes. JUnit 4.1 is our test framework
+
--- End diff --
We could just say the latest version of Junit is our test framework instead of calling out a specific version
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-samoa pull request: SAMOA-13: Update "How to contribute"...
Posted by gdfm <gi...@git.apache.org>.
Github user gdfm commented on a diff in the pull request:
https://github.com/apache/incubator-samoa/pull/6#discussion_r25952157
--- Diff: CONTRIBUTING.md ---
@@ -1,18 +1,74 @@
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 install`
+
+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 install -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 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`).
+* New unit tests should be provided to demonstrate bugs and fixes. JUnit 4.1 is our test framework
+
+### Organization of the code changes
+
+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 ([currently being defined](https://issues.apache.org/jira/browse/SAMOA-5))
--- End diff --
Now we have bylaws, can link to them directly.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-samoa pull request: SAMOA-13: Update "How to contribute"...
Posted by arinto <gi...@git.apache.org>.
Github user arinto commented on the pull request:
https://github.com/apache/incubator-samoa/pull/6#issuecomment-77790284
+1
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-samoa pull request: SAMOA-13: Update "How to contribute"...
Posted by gdfm <gi...@git.apache.org>.
Github user gdfm commented on the pull request:
https://github.com/apache/incubator-samoa/pull/6#issuecomment-87585787
Seems there are some build issues.
@matthieumorel are you able to have a look at them?
Otherwise I will try to fix them later this week.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-samoa pull request: SAMOA-13: Update "How to contribute"...
Posted by gdfm <gi...@git.apache.org>.
Github user gdfm commented on the pull request:
https://github.com/apache/incubator-samoa/pull/6#issuecomment-77578665
Apart form the small fixes above, +1
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-samoa pull request: SAMOA-13: Update "How to contribute"...
Posted by gdfm <gi...@git.apache.org>.
Github user gdfm commented on a diff in the pull request:
https://github.com/apache/incubator-samoa/pull/6#discussion_r25952320
--- Diff: CONTRIBUTING.md ---
@@ -1,18 +1,74 @@
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 install`
+
+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 install -Pall`
--- End diff --
This installs the artifacts. I prefer suggesting "mvn clean package -Pall"
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-samoa pull request: SAMOA-13: Update "How to contribute"...
Posted by gdfm <gi...@git.apache.org>.
Github user gdfm commented on the pull request:
https://github.com/apache/incubator-samoa/pull/6#issuecomment-88859161
Thanks, it looks OK.
I opened a PR to your branch to address the comments in this thread.
If you review them, merge them, and push to the PR I will commit it to the master branch.
If you cannot do that, just +1 to the changes on this thread and I will commit them.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-samoa pull request: SAMOA-13: Update "How to contribute"...
Posted by smarthi <gi...@git.apache.org>.
Github user smarthi commented on a diff in the pull request:
https://github.com/apache/incubator-samoa/pull/6#discussion_r24120074
--- Diff: CONTRIBUTING.md ---
@@ -1,18 +1,73 @@
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 install`
+
+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 install -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, with the following exceptions:
--- End diff --
Not sure what the Sun conventions with regards to imports. We should avoid all import *, that's something that's strictly adhered to in other projects like Mahout, Flink, Oryx. Also a line or 2 about the order of imports would be good.
Typically its been
{Code}
import java.*
<space>
import 3rd party library implementations
<space>
import project specific classes
{Code}
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-samoa pull request: SAMOA-13: Update "How to contribute"...
Posted by matthieumorel <gi...@git.apache.org>.
GitHub user matthieumorel reopened a pull request:
https://github.com/apache/incubator-samoa/pull/6
SAMOA-13: Update "How to contribute" guidelines
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/matthieumorel/incubator-samoa SAMOA-13
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/incubator-samoa/pull/6.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #6
----
commit 127841223983b4fe64018cab992c3ebc273d65f5
Author: Matthieu Morel <mm...@apache.org>
Date: 2015-02-02T13:24:38Z
Update "How to contribute" guidelines
- amended with suggestions
----
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-samoa pull request: SAMOA-13: Update "How to contribute"...
Posted by gdfm <gi...@git.apache.org>.
Github user gdfm commented on a diff in the pull request:
https://github.com/apache/incubator-samoa/pull/6#discussion_r25952201
--- Diff: CONTRIBUTING.md ---
@@ -1,18 +1,74 @@
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 install`
+
+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 install -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 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`).
+* New unit tests should be provided to demonstrate bugs and fixes. JUnit 4.1 is our test framework
+
+### Organization of the code changes
+
+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 ([currently being defined](https://issues.apache.org/jira/browse/SAMOA-5))
+
+
+
+
+
+
+[^1]: You need to be logged into ASF's JIRA and use the create button on [this page](https://issues.apache.org/jira/browse/SAMOA/?selectedTab=com.atlassian.jira.jira-projects-plugin:summary-panel).
--- End diff --
Maybe remove the GET parameters in the URL?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---