gearpump-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From manuzhang <...@git.apache.org>
Subject [GitHub] incubator-gearpump pull request: gearpump-34 update developer docu...
Date Sat, 16 Apr 2016 08:26:03 GMT
Github user manuzhang commented on a diff in the pull request:

    https://github.com/apache/incubator-gearpump/pull/1#discussion_r59964495
  
    --- 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.
    +
    +Before submitting a PR, you should always run style check first:
    +```
    +  ## Run style check for compile, test, and integration test.
    +  sbt scalastyle test:scalastyle it:scalastyle
    +```
    +
    +<a name="write-unittest"></a>
    +## How to write unit test
    +TBD
    +
    +<a name="write-integrationtest"></a>
    +## How to write integration test
    +TBD
    +
    +<a name="write-doc"></a>
    +## How to write document
    +Documentation contributions are very welcome!
    +
    +You can contribute documentation by pull request, as same as code contribution.
    +Main directory is ```docs/```, and you can refer to docs/README.md for how to build /
test documentation.
    +
    +NOTE: this documentation is the release documentation for Gearpump, not the website documentation
at Apache website, which was maintained by another repository.
    +
    +
    +<a name="committer-work"></a>
    +# Committer section
    +_This section applies to committers only._
    +
    +<a name="approve-pull-request"></a>
    +## Approve pull request
    +It's committer's duty to review pull requests from contributors. 
    +
    +Any PR ready to merge shall have at least one +1(s) and no -1(s). And any merge shall
wait another 24 hours after the first +1 received to wait for potential comments.
    +Only committer has the right to perform PR merge to Apache upstream.
    +
    +
    +<a name="merge-pull-request"></a>
    +## Merge pull request
    +For each committer, it is suggested to make a local clone of Apache Gearpump repository
and make it solely for PR merge purpose. 
    +```bash
    +git clone https://git-wip-us.apache.org/repos/asf/incubator-gearpump
    +
    +```
    +**NOTE: Only Apache Gearpump repository is writable. The github mirror is READONLY.
    +
    --- End diff --
    
    missing trailing "**"


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

Mime
View raw message