Github user manuzhang commented on a diff in the pull request:
https://github.com/apache/incubator-gearpump/pull/1#discussion_r60530264
--- Diff: CONTRIBUTING.md ---
@@ -1,92 +1,378 @@
-This documents are for committers which have direct write permission to
intel-hadoop/gearpump
+# Developer documentation
-Commit Guideline
-========================
-1. For all commit(except doc), must create an issue id.
-2. For all commit log message, must contain the issue id, Like this: fix
#issueId, comments.
-3. For all PR, the title must contains issue Id.
-4. We use rebase and squash instead of merge to ensure the log message is
clean. Check section "Pull Request merge process for Gearpump"
-5. Every commit (except doc) must have 1 guy to review before commit.
+This document summarizes the information relevant to Gearpump committers
and contributors. It includes information about
+the development processes and policies as well as the tools we use to
facilitate those.
-Pull Request merge process for Gearpump
-========================
-1. Fork in github to create a /gearpump repo. After fork, you will have a
new repo at http://github.com/<git-user_id>/gearpump.
-2. Add gearpump/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/gearpump/gearpump.git
- ```
+Table of Contents
+* <a href="#welcome">Welcome!</a>
+* <a href="#workflow">Contribution workflow</a>
+ * <a href="#report-bug">Report a bug</a>
+ * <a href="#request-feature">Request a new feature</a>
+ * <a href="#contribute-code">Contribute code/document by creating a
Pull Request</a>
+ * <a href="code-review">Code Review</a>
+* <a href="#build-and-test">Build the code and run the tests</a>
+ * <a href="#local-copy">Make a local copy of Gearpump</a>
+ * <a href="#build">How to build</a>
+ * <a href="#test">How to test</a>
+ * <a href="#build-doc">How to build document</a>
+ * <a href="#ide-setup">IDE setup</a>
+ * <a href="#code-style">Code style</a>
+ * <a href="#write-unittest">How to write unit test</a>
+ * <a href="#write-integrationtest">How to write integration test</a>
+ * <a href="#write-doc">How to write document</a>
+* <a href="#committer-work">Committer section</a>
+ * <a href="#approve-pull-request">Approve a pull request</a>
+ * <a href="#merge-pull-request">Merge a pull request or patch</a>
+ * <a href="#release">How to make a release</a>
-3. In local master branch, periodically sync the forked master with the
main master with
-
- ```
- git pull --rebase upstream master
- git push origin master
- ```
-No work should ever be done in the forked master. Another way to do this
is to
+---
- ```
- git checkout master
- git fetch upstream
- git rebase upstream/master
- ```
+<a name="welcome"></a>
+
+# Welcome!
+
+If you are reading this document then you are interested in contributing
to the Gearpump project -- many thanks for that!
+All contributions are welcome: ideas, documentation, code, patches, bug
reports, feature requests, etc.
+
+
+<a name="workflow"></a>
+# Contribution workflow
+
+This section explains how to make a contribution.
+
+
+<a name="report-bug"></a>
+
+## Report a bug
+
+To report a bug you should [open an
issue](https://issues.apache.org/jira/browse/GEARPUMP) in our issue tracker that
+summarizes the bug. Set the form field "Issue type" to "Bug". If you
have not used the issue tracker before you will
+need to register an account (free), log in, and then click on the red
"Create Issue" button in the top navigation bar.
+
+In order to help us understand and fix the bug it would be great if you
could provide us with:
+
+1. The steps to reproduce the bug. This includes information about e.g.
the Gearpump version you were using, the deployment model, etc.
+2. The expected behavior.
+3. The actual, incorrect behavior.
+
+Feel free to search the issue tracker for existing issues (aka tickets)
that already describe the problem; if there is
+such a ticket please add your information as a comment.
+
+**If you want to provide a patch along with your bug report:**
+That is great! In this case please send us a pull request as described in
section [Create a pull request](#create-pr) below.
+You can also opt to attach a patch file to the issue ticket, but we prefer
pull requests because they are easier to work
+with.
+
+
+<a name="request-feature"></a>
+
+## Request a new feature
+
+To request a new feature you should [open an
issue](https://issues.apache.org/jira/browse/GEARPUMP) in our issue tracker
+and summarize the desired functionality. Set the form field "Issue type"
to "New feature". If you have not used the
+issue tracker before you will need to register an account (free), log in,
and then click on the blue "Create Issue"
+button in the top navigation bar.
-4. Create a working branch
+
+<a name="contribute-code"></a>
+
+## Contribute code/document by creating Pull Request
+Before you set out to contribute code we recommend that you familiarize
yourself with the Gearpump codebase and corresponding development document at
Gearpump website.
+
+_If you are interested in contributing code to Gearpump but do not know
where to begin:_
+In this case you should
+[browse our issue tracker for open issues and
tasks](https://issues.apache.org/jira/browse/GEARPUMP/?selectedTab=com.atlassian.jira.jira-projects-plugin:issues-panel).
+
+Contributions to the Gearpump codebase should be sent as GitHub pull
requests. See section [Create a pull request](#create-pr) below
+for details. If there is any problem with the pull request we can iterate
on it using the commenting features of
+GitHub.
+
+* For _small patches_, feel free to submit pull requests directly for
those patches.
+* For _larger code contributions_, please use the following process. The
idea behind this process is to prevent any
+ wasted work and catch design issues early on.
+
+ 1. [Open an issue](https://issues.apache.org/jira/browse/GEARPUMP) on
our issue tracker if a similar issue does not
+ exist already. If a similar issue does exist, then you may
consider participating in the work on the existing
+ issue.
+ 2. Comment on the issue with your plan for implementing the issue.
Explain what pieces of the codebase you are
+ going to touch and how everything is going to fit together.
+ 3. Gearpump committers will iterate with you on the design to make
sure you are on the right track.
+ 4. Implement your issue, create a pull request (see below), and
iterate from there.
+
+
+### Contribution Guideline
+1. For all commits, must create an issue id.
+2. For all commit log messages, must contain the issue id, Like this: fix
#issueId, comments.
+3. For all PRs (pull request), the title must contains issue Id.
+4. We use rebase and squash instead of merge to ensure the log message is
clean. Check section "Pull Request merge process for Gearpump"
+5. Every commit (except doc) must have 1 committer to review before commit.
+
+<a name="create-pr"></a>
+### Create a Pull Request
+Before working on code contribution, you need to prepare your [development
environment](#build-and-test).
+
+To work on a code contribution, following process is suggested:
+
+1. You need to create a working branch (before that, please make sure your
local master is synced with **upstream** master.)
```
git branch branch_issueId
- git checkout branch_issusId
+ git checkout branch_issueId
```
- Work on the branch, make changes, then push to your forked gearpump repo
http://github.com/<git-user_id>/gearpump
+ Work on the branch, make changes, then push to your forked Gearpump repo
http://github.com/<git-user_id>/incubator-gearpump.
```
git push origin branch_issueId
```
-5. When there is changes in upstream/master, rebase your work on
upstream/master. with
+2. When there are changes in upstream/master, rebase your work on
upstream/master.
```bash
git checkout branch_issueId
git rebase -i upstream/master
```
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".
+ ```git rebase -i``` will pop up a window, which allow you to
squash(merge) multiple commits into one commit.
+ 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 environment 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 plan 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
upstream 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.
--- End diff --
Mac, I think
---
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 [email protected] or file a JIRA ticket
with INFRA.
---
