Mailing-List: contact dev-help@gearpump.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@gearpump.incubator.apache.org
From: whjiang <git@git.apache.org>
To: dev@gearpump.incubator.apache.org
Reply-To: dev@gearpump.incubator.apache.org
References: <git-pr-1-incubator-gearpump@git.apache.org>
In-Reply-To: <git-pr-1-incubator-gearpump@git.apache.org>
Subject: [GitHub] incubator-gearpump pull request: gearpump-34 update
 developer docu...
Content-Type: text/plain
Message-Id: <20160417140425.EB8B0DFB73@git1-us-west.apache.org>
Date: Sun, 17 Apr 2016 14:04:25 +0000 (UTC)

Github user whjiang commented on a diff in the pull request:

    https://github.com/apache/incubator-gearpump/pull/1#discussion_r59985019
  
    --- Diff: CONTRIBUTING.md ---
    @@ -53,40 +137,242 @@ No work should ever be done in the forked master. Another way to do this is to
     
        You can also use this when you want to squash(merge) multiple commits into one.
        ```git rebase -i``` will popup a window, which allow you to squash(merge) multiple commits into one commit.
    -   For example I might have 12 commits in my branch. "rebase -i upstream/master" opens a nice editor where you can mark some commits to be squashed(merged) into prior commits, and make 1 big commit (or several) out of it. In this way, I can tidy up what will be committed to the project master's history since otherwise my commit messages are like "not working" or "got it working" or "more fix" or "merged <git-user-id>/gearpump to master".
    +   For example I might have 12 commits in my branch. ```git rebase -i upstream/master``` opens a nice editor where you can mark some commits to be squashed(merged) into prior commits, and make 1 big commit (or several) out of it. In this way, I can tidy up what will be committed to the project master's history since otherwise my commit messages are like "not working" or "got it working" or "more fix" or "merged <git-user-id>/gearpump to master".
     
    -6. If there is conflict, resolve the conflict, and then 
    +3. If there is conflict, resolve the conflict, and then 
     
       ```bash
        git rebase --continue  
       ```
     
       After the code is successfully rebased, a window will pop up to edit the commit log, edit it then save and exit.
    -7. After rebase, now you have a clean log history. push to your remote working branch
    +4. After rebase, now you have a clean log history. push to your remote working branch
     
       ```
       git push origin branch_issueId
       ```
     
    -  If commits have already been pushed to <git-user-id>/gearpump fork on github, you will have to "git push --force" to overwrite them with squashed commits.
    +  If commits have already been pushed to your <git-user-id>/incubator-gearpump fork on github, you will have to "git push --force" to overwrite them with squashed commits.
     
       ```
       git push origin -f branch_issueId
       ```
     
    -8. Ensure all the unit tests are passed by running command "sbt test".
    -6. Open a PR, which is a one-click thing in github.com; it knows you likely are opening a PR against upstream master. [Guide](https://help.github.com/articles/creating-a-pull-request) is here.
    -7. [Merge PR](https://help.github.com/articles/merging-a-pull-request), [delete branch](https://help.github.com/articles/deleting-unused-branches).
    +5. Ensure all the unit tests and integration tests are passed, check [Test](#test) for details.
    +6. Open a Pull Request, which is a one-click thing in github.com; it knows you likely are opening a PR against upstream master. [Guide](https://help.github.com/articles/creating-a-pull-request) is here.
    +
    +<a name="code-review"></a>
    +# Code Review
    +Committer will review your code periodically. When there is any comment/feedback from committer(s), it's contributor's duty to update the pull request correspondingly. 
    +
    +When the merge was done by committer, you can optionally [delete your PR branch](https://help.github.com/articles/deleting-unused-branches).
    +
    +
    +<a name="build-and-test"></a>
    +
    +# Build and test
    +Though without a development environment setup, you can still contribute to Gearpump by reporting ideas, documentations, bug reports and feature requests.
    +It is highly recommended to set up a development emnvironment to make any code contribution.
    +
    +<a name="local-copy"></a>
    +## Clone Gearpump repository and make a local copy
    +If you just want to study Gearpump source code, it is optional to perform following steps. 
    +But, if you plans to contribute to Gearpump's code base, it is necessary to perform following steps:
    +
    +1. [Fork](https://help.github.com/articles/fork-a-repo) in github from https://github.com/apache/incubator-gearpump to create a /incubator-gearpump repo. 
    +After fork, you will have a new repo at https://github.com/<git-user_id>/incubator-gearpump.
    +
    +2. Clone the forked repo at your computer.
    +
    +  ```bash
    +  git clone https://github.com/<git-user_id>/incubator-gearpump
    +  cd incubator-gearpump
    +  ```
    +
    +3. Add apache/incubator-gearpump as an external repo 'upstream' by following the [guide](https://help.github.com/articles/configuring-a-remote-for-a-fork/).
    +
    +  ```bash
    +  git remote add upstream https://github.com/apache/incubator-gearpump.git
    +  ```
    +
    +4. In local master branch, periodically sync the forked master with the main master with 
    + 
    +  ```bash
    +   git pull --rebase upstream  master
    +   git push origin master
    +  ``` 
    +
    +Another way to do this is to 
    +
    + ```bash
    +   git checkout master
    +   git fetch upstream
    +   git rebase upstream/master
    + ```
    +
    +No development work should ever be done in the forked master. 
    +
    +<a name="build"></a>
    +## How to build
    +To make a compilation of Gearpump, you can execute:
    +```bash
    +  sbt compile pack
    +```
    +
    +To build a Gearpump package, you can execute following commands:
    +
    +```bash
    +  ## The target package path: output/target/gearpump-${version}.zip
    +  sbt clean +assembly +packArchiveZip
    +```
    +
    +  After the build, there will be a package file gearpump-${version}.zip generated under output/target/ folder.
    +
    +  **NOTE:**
    +The build requires network connection. If you are behind a proxy, make sure you have set the proxy in your env before running the build commands.
    +For windows:
    +
    +```bash
    +set HTTP_PROXY=http://host:port
    +set HTTPS_PROXY= http://host:port
    +```
    +
    +For Linux:
    +
    +```bash
    +export HTTP_PROXY=http://host:port
    +export HTTPS_PROXY= http://host:port
    +```
    +<a name="test"></a>
    +## How to test
    +Unit tests and Integration tests are an essential part of code contributions.
    +
    +To run unit test, you can run
    +```bash
    +  sbt test
    +```
    +
    +Gearpump has an integration test system which is based on Docker. Please check [the instructions](integrationtest/README.md).
    +
    +<a name="build-doc"></a>
    +## How to build Gearpump documentation
    +To build Gearpump document, use
    +```bash
    +   ## the 2nd argument indicates whether to build API doc or not
    +   ## for release, we need to use '1' to build it (time consuming)
    +   docs/build_doc.sh  2.11  0 
    +```  
    +
    +<a name=IDE-setup"></a>
    +## IDE setup
    +IDE environment can be set up on either Windows, Linux and MAC platform. You can choose the one you prefer. 
    +The IDE setup guide can be found at [Gearpump website](http://www.gearpump.io/releases/latest/dev-ide-setup.html).
    +
    +It is highly recommended to perform [package build](#build) before IDE setup.
    +
    +<a name="code-style"></a>
    +## Gearpump code style
    +
    +Gearpump follows the standard Scala style, just like other Scala projects. This style is:
    +
    +1. Mainly, we follow the [Spark Scala style](https://github.com/databricks/scala-style-guide).
    +
    +2. We allows some exceptions: e.g. allowing using !, ? for Akka to send actor message.
    --- End diff --
    
    yes. can anyone give me a full list of exceptions?


---
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.
---