apex-site git commit: APEXCORE-534 Improve contributor setup instructions.

[ch...@apache.org]

Repository: apex-site
Updated Branches:
  refs/heads/master c3a284ba0 -> bcc8bd50e


APEXCORE-534 Improve contributor setup instructions.


Project: http://git-wip-us.apache.org/repos/asf/apex-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/apex-site/commit/bcc8bd50
Tree: http://git-wip-us.apache.org/repos/asf/apex-site/tree/bcc8bd50
Diff: http://git-wip-us.apache.org/repos/asf/apex-site/diff/bcc8bd50

Branch: refs/heads/master
Commit: bcc8bd50eb63c7c095b587ebf7c7a10890fab819
Parents: c3a284b
Author: Thomas Weise <th...@datatorrent.com>
Authored: Wed Sep 14 17:36:05 2016 -0700
Committer: Thomas Weise <th...@datatorrent.com>
Committed: Thu Sep 15 23:33:26 2016 -0700

----------------------------------------------------------------------
 src/md/contributing.md | 64 +++++++++++++++++++++++++++++++--------------
 1 file changed, 44 insertions(+), 20 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/apex-site/blob/bcc8bd50/src/md/contributing.md
----------------------------------------------------------------------
diff --git a/src/md/contributing.md b/src/md/contributing.md
index 2df4480..21198ed 100644
--- a/src/md/contributing.md
+++ b/src/md/contributing.md
@@ -14,32 +14,55 @@ This project welcomes new contributors and invites everyone to participate. Our
 
 People that help with the project in any of the above categories or other ways are contributors. See the [roles](http://www.apache.org/foundation/how-it-works.html#roles) as defined by the ASF. Community members that make sustained, welcome contributions to the project may be invited to become a [committer](/people.html). 
 
-## Code Style
+## One-time Setup
 
-Apache Apex follows coding style that is closest to K & R style and uses [Checkstyle](http://checkstyle.sourceforge.net/) tool to enforce these standards. Travis CI will fail for any pull request that introduces any style violations.
+### JIRA
 
-The checkstyle configuration that Apache Apex projects use is present here : https://github.com/apache/apex-core/blob/master/codestyle-config/src/main/resources/apex_checks.xml
+Apache JIRA is used for issue tracking. If you do not already have an Apache JIRA account, sign up [here](https://issues.apache.org/jira/). Note that the user name should have no white spaces or other special characters that complicate auto-completion within JIRA comments etc. 
+
+Please use a single JIRA account only (don't create multiple with different email addresses) to retain the issue history. Please use a permanent email address, for an existing account it can be changed in the profile. If you absolutely have to change your user name, contact INFRA.
+
+Apex has 2 JIRA projects:
+
+1. [APEXCORE](https://issues.apache.org/jira/browse/APEXCORE/) for [apex-core](https://github.com/apache/apex-core) and [apex-site](https://github.com/apache/apex-site)
+2. [APEXMALHAR](https://issues.apache.org/jira/browse/APEXMALHAR/) for [apex-malhar](https://github.com/apache/apex-malhar)
+
+Before working on changes for any of the repositories, please locate an existing JIRA ticket or submit a new one. In order to assign an issue to yourself, you need to be listed as contributor in the JIRA project. PMC members have access to add new contributors, please request to be added through a comment on your candidate ticket or send us an email on the dev@ mailing list.
+
+### Github and git
+
+We use GitHub\u2019s pull request functionality to review proposed code changes. If you do not already have a personal GitHub account, sign up [here](https://github.com/join). We recommend that you use the same email address and first/lastname for emails, git and JIRA so that contributions can be better tracked and notifications correlated. It is also recommended that you use an email address that is valid permanently (for example your @gmail.com or @apache.org address). Please also see:
+
+* https://help.github.com/articles/setting-your-email-in-git/
+* https://help.github.com/articles/adding-an-email-address-to-your-github-account/
+* https://help.github.com/articles/keeping-your-email-address-private/
+
+If you are new to git, this [tutorial](https://try.github.io/) may be helpful.
+
+The ASF Apex git repositories have mirror repositories on github which are used to review pull requests and provide a second remote endpoint for the codebase.
+
+1. Fork the ASF github mirror: https://github.com/apache/apex-core (or https://github.com/apache/apex-malhar or https://github.com/apache/apex-site) 
+1. Clone the **fork** on your local workspace (one time step):<br/>
+   `git clone https://github.com/{github_username}/apex-core.git`
+1. Add the mirror as remote repository, here shown for apex-core:<br/>
+   `git remote add upstream https://github.com/apache/apex-core`
+
+### Java Development Environment
+
+For prerequisites and setup instructions see: http://apex.apache.org/docs/apex/apex_development_setup/
+
+Apache Apex follows coding style that is closest to K & R style and uses [Checkstyle](http://checkstyle.sourceforge.net/) tool to enforce these standards. Travis CI will fail for any pull request that introduces any style violations. The checkstyle configuration is [here](https://github.com/apache/apex-core/blob/master/codestyle-config/src/main/resources/apex_checks.xml).
 
 To make it easier for the users to set up their development environment, settings for the following common IDEs are provided in the Apache Apex Core repository with instructions.
  - [IntelliJ](https://github.com/apache/apex-core/tree/master/misc/ide-templates/intellij)
  - [Eclipse](https://github.com/apache/apex-core/tree/master/misc/ide-templates/eclipse)
  - [NetBeans](https://github.com/apache/apex-core/tree/master/misc/ide-templates/netbeans)
 
-## Opening Pull Requests (contributors)
-
-The apex-core and apex-malhar repositories both have mirror repositories on github which are used to review pull requests and provide a second remote endpoint for the codebase.
-
-1. Create/assign a JIRA ([-core](https://issues.apache.org/jira/browse/APEXCORE/),[-malhar](https://issues.apache.org/jira/browse/APEXMALHAR/)) for the work you plan to do (or assign yourself to an existing JIRA ticket)
-1. Fork the ASF github mirror (one time step):
-   https://github.com/apache/apex-core/  
-1. Clone the **fork** on your local workspace (one time step):  
-  `git clone https://github.com/{github_username}/apex-core.git`
-1. Add [apex core](https://github.com/apache/apex-core) as a remote repository (one time step):  
-`git remote add upstream https://github.com/apache/apex-core`
-1. Ensure that your git user name and email are [configured](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup#Your-Identity), this will make it much easier to keep track of contributors (one time step).
-1. Create a new branch from the [master](https://github.com/apache/apex-core/tree/master) branch. **Name your branch with the JIRA number in it, e.g. `APEXCORE-123.my-feature`.**  
-`git checkout -b APEXCORE-123.my-feature -t upstream/master`  
-Creating a local branch that tracks a remote makes pull easier (no need to specify the remote branch while pulling). A branch can be made to track a remote branch anytime, not necessarily at its creation by:  
+## Opening Pull Requests
+
+1. Create a new branch from the `master` branch, **name it with the JIRA number, e.g. `APEXCORE-123.my-feature`**:<br/>
+`git checkout -b APEXCORE-123.my-feature -t upstream/master`<br/>
+Creating a local branch that tracks a remote makes pull easier (no need to specify the remote branch while pulling). A branch can be made to track a remote branch anytime, not necessarily at its creation by:<br/>
 `git branch -u upstream/master`
 1. When adding new files, please include the Apache v2.0 license header.
   - From the top level directory, run `mvn license:check -Dlicense.skip=false` to check correct header formatting.
@@ -52,7 +75,7 @@ Creating a local branch that tracks a remote makes pull easier (no need to speci
 1. Add changes after the PR was opened to the same branch, Travis CI will detect changes and build automatically. To force the CI run, close and re-open the PR.
 1. After all review is complete, combine all new commits into one squashed commit except when there are multiple contributors, and include the Jira number in the commit message. There are several ways to squash commits, but [here is one explanation from git-scm.com](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Squashing-Commits) and a simple example is illustrated below:
 
-  If tracking upstream/master then run `git rebase -i`. Else run `git rebase -i upstream/master`.  
+  If tracking upstream/master then run `git rebase -i`. Else run `git rebase -i upstream/master`.
   This command opens the text editor which lists the multiple commits:
 
   ```
@@ -105,7 +128,8 @@ Thanks for contributing!
   - Travis CI pull request build needs to pass
   - Ensure tests are added/modified for new features or fixes
   - Ensure appropriate JavaDoc comments have been added
-1. To set up access to the ASF source repository, [follow these steps](https://git-wip-us.apache.org/#committers-getting-started). The ASF master repository is: `https://git-wip-us.apache.org/repos/asf/apex-core.git`
+1. To set up access to the ASF source repository, [follow these steps](https://git-wip-us.apache.org/#committers-getting-started). The ASF master repository is:<br/>
+   `https://git-wip-us.apache.org/repos/asf/apex-core.git`
 1. Use the git command line to pull in the changes from the pull requests. You can refer to the corresponding email that will be automatically sent to the `dev@apex.apache.org` mailing list to see the exact commands to merge the given pull request.
 1. Once done with verification, push the changes to the ASF repository's `master` branch. Within a few
 seconds, the changes will propagate back to the github mirror and the pull requests be closed and marked merged automatically.