You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@submarine.apache.org by pi...@apache.org on 2021/03/10 03:36:44 UTC
[submarine] branch master updated: SUBMARINE-748. Update
Contributing guide
This is an automated email from the ASF dual-hosted git repository.
pingsutw pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/submarine.git
The following commit(s) were added to refs/heads/master by this push:
new 66907f3 SUBMARINE-748. Update Contributing guide
66907f3 is described below
commit 66907f3f259cdbdc12a38aee6a6e6ef314de467d
Author: Kai-Hsun Chen <b0...@ntu.edu.tw>
AuthorDate: Tue Mar 9 19:22:37 2021 -0800
SUBMARINE-748. Update Contributing guide
### What is this PR for?
Update Contributing guide
### What type of PR is it?
[Documentation]
### Todos
### What is the Jira issue?
https://issues.apache.org/jira/browse/SUBMARINE-748
### How should this be tested?
### Screenshots (if appropriate)
### Questions:
* Does the licenses files need update? No
* Is there breaking changes for older versions? No
* Does this needs documentation? No
Author: Kai-Hsun Chen <b0...@ntu.edu.tw>
Author: Kevin Su <pi...@gmail.com>
Signed-off-by: Kevin <pi...@apache.org>
Closes #519 from kevin85421/SUBMARINE-748 and squashes the following commits:
a5cda74a [Kevin Su] Update website/docs/community/contributing.md
f918cc0f [Kai-Hsun Chen] SUBMARINE-748. Update Contributing guide
7a964c17 [Kai-Hsun Chen] SUBMARINE-748. Update Contributing guide
f20a1e82 [Kai-Hsun Chen] SUBMARINE-748. Update Contributing guide
---
.../docs/assets/compare_pull_request_button.png | Bin 0 -> 187503 bytes
website/docs/assets/jira_number_example.png | Bin 0 -> 207580 bytes
.../docs/assets/pull_request_template_example.png | Bin 0 -> 333584 bytes
website/docs/community/contributing.md | 288 ++++++---------------
4 files changed, 84 insertions(+), 204 deletions(-)
diff --git a/website/docs/assets/compare_pull_request_button.png b/website/docs/assets/compare_pull_request_button.png
new file mode 100644
index 0000000..029a39f
Binary files /dev/null and b/website/docs/assets/compare_pull_request_button.png differ
diff --git a/website/docs/assets/jira_number_example.png b/website/docs/assets/jira_number_example.png
new file mode 100644
index 0000000..b443295
Binary files /dev/null and b/website/docs/assets/jira_number_example.png differ
diff --git a/website/docs/assets/pull_request_template_example.png b/website/docs/assets/pull_request_template_example.png
new file mode 100644
index 0000000..84d9550
Binary files /dev/null and b/website/docs/assets/pull_request_template_example.png differ
diff --git a/website/docs/community/contributing.md b/website/docs/community/contributing.md
index 18f32ce..faa50f9 100644
--- a/website/docs/community/contributing.md
+++ b/website/docs/community/contributing.md
@@ -1,5 +1,5 @@
---
-title: Guide for Apache Submarine Contributor
+title: How To Contribute to Submarine
---
<!--
@@ -15,252 +15,132 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
+There are several ways to contribute to Submarine:
+1. Develop and Commit source code (This document will primarily focus on this.)
+2. Report issues (You can report issues with both Github or Jira.)
+3. Discuss/Answer questions on the mailing list
+4. Share use cases
-**Apache Submarine** is an [Apache 2.0 License](https://github.com/apache/submarine/blob/master/LICENSE) Software.
+## Preface
+* **Apache Submarine** is an [Apache 2.0 License](https://github.com/apache/submarine/blob/master/LICENSE) Software. Contributing to Submarine means you agree to the Apache 2.0 License.
+* Please read [Code of Conduct](http://www.apache.org/foundation/policies/conduct.html) carefully.
+* The document [How It Works](http://www.apache.org/foundation/how-it-works.html) can help you understand Apache Software Foundation further.
-Contributing to Submarine (Source code, Documents, Image, Website) means you agree to the Apache 2.0 License.
+## Build Submarine
+* [Build From Code](https://github.com/apache/submarine/blob/master/website/docs/devDocs/BuildFromCode.md)
-1. Make sure your issue is not already in the [Jira issue tracker](https://issues.apache.org/jira/browse/SUBMARINE)
-2. If not, create a ticket describing the change you're proposing in the [Jira issue tracker](https://issues.apache.org/jira/browse/SUBMARINE)
-3. Setup Travis [Continuous Integration](#continuous-integration)
-4. Contribute your patch via Pull Request on our [Github Mirror](https://github.com/apache/submarine).
-
-Before you start, please read the [Code of Conduct](http://www.apache.org/foundation/policies/conduct.html) carefully, familiarize yourself with it and refer to it whenever you need it.
-
-For those of you who are not familiar with the Apache project, understanding [How it works](http://www.apache.org/foundation/how-it-works.html) would be quite helpful.
-
-## Creating a Pull Request
-When creating a Pull Request, you will automatically get the template below.
-
-Filling it thoroughly can improve the speed of the review process.
-
- ### What is this PR for?
- A few sentences describing the overall goals of the pull request's commits.
- First time? Check out the contribution guidelines -
- https://github.com/apache/submarine/tree/master/docs/community/contributing.md
-
- ### What type of PR is it?
- [Bug Fix | Improvement | Feature | Documentation | Hot Fix | Refactoring]
-
- ### Todos
- * [ ] - Task
-
- ### What is the Jira issue?
- * Open an issue on Jira https://issues.apache.org/jira/browse/SUBMARINE/
- * Put link here, and add [SUBMARINE-${jira_number}] in PR title, e.g. [SUBMARINE-323]
-
- ### How should this be tested?
- Outline the steps to test the PR here.
-
- ### Screenshots (if appropriate)
-
- ### Questions:
- * Do the licenses files require updates?
- * Are there breaking changes for older versions?
- * Does this need documentation?
-
-
-## Source Control Workflow
+## Creating patches
Submarine follows [Fork & Pull](https://github.com/sevntu-checkstyle/sevntu.checkstyle/wiki/Development-workflow-with-Git:-Fork,-Branching,-Commits,-and-Pull-Request) model.
-## The Review Process
-
-When a Pull Request is submitted, it is being merged or rejected by the following review process.
-
-* Anybody can be a reviewer and may comment on the change or suggest modifications.
-* Reviewer can indicate that a patch looks suitable for merging with a comment such as: "Looks good", "LGTM", "+1".
-* At least one indication of suitability (e.g. "LGTM") from a committer is required to be merged.
-* Pull request is open for 1 or 2 days for potential additional review unless it's got enough indication of suitability.
-* A committer can then initiate lazy consensus ("Merge if there is no more discussion") after which the code can be merged after a particular time (usually 24 hours) if there are no more reviews.
-* Contributors can ping reviewers (including committers) by commenting 'Ready to review' or suitable indication.
-
-
-## Setting up
-Here are some things you will need to build and test the Submarine.
-
-### Software Configuration Management (SCM)
-
-Submarine uses Git for its SCM system. So you'll need a git client installed on your development machine.
-
-### Integrated Development Environment (IDE)
-
-You are free to use whatever IDE you prefer, or your favorite command-line editor.
-
-### Code convention
-We are following Google Code style:
-
-* [Java style](https://google.github.io/styleguide/javaguide.html)
-* [Shell style](https://google.github.io/styleguide/shell.xml)
-
-There are some plugins to format, lint your code in IDE (use [dev-support/maven-config/checkstyle.xml](hhttps://github.com/apache/submarine/blob/master/dev-support/maven-config/checkstyle.xml) as rules)
-
-* [Checkstyle plugin for Intellij](https://plugins.jetbrains.com/plugin/1065) ([Setting Guide](http://stackoverflow.com/questions/26955766/intellij-idea-checkstyle))
-* [Checkstyle plugin for Eclipse](http://eclipse-cs.sourceforge.net/#!/) ([Setting Guide](http://eclipse-cs.sourceforge.net/#!/project-setup))
-
-
-## Getting the source code
-
-### Step 1: Fork in the cloud
-
-1. Visit https://github.com/apache/submarine
-2. On the top right of the page, click the `Fork` button (top right) to create a cloud-based fork of the repository.
-
-### Step 2: Clone fork to local storage
-
-Create your clone:
-
-> ${user} is your github user name
+### Step1: Fork apache/submarine github repository (first time)
+* Visit https://github.com/apache/submarine
+* Click the `Fork` button to create a fork of the repository
+### Step2: Clone the Submarine to your local machine
```sh
-mkdir -p ${working_dir}
-cd ${working_dir}
-
-git clone https://github.com/${user}/submarine.git
-# or: git clone git@github.com:${user}/submarine.git
-
-cd ${working_dir}/submarine
-git remote add upstream https://github.com/apache/submarine.git
-# or: git remote add upstream git@github.com:apache/submarine.git
-
-# Never push to the upstream master.
+# USERNAME – your Github user account name.
+git clone git@github.com:${USERNAME}/submarine.git
+# or: git clone https://github.com/${USERNAME}/submarine.git
+
+cd submarine
+# set upstream
+git remote add upstream git@github.com:apache/submarine.git
+# or: git remote add upstream https://github.com/apache/submarine.git
+
+# Don't push to the upstream master.
git remote set-url --push upstream no_push
-# Confirm that your remotes make sense:
-# It should look like:
-# origin git@github.com:${user}/submarine.git (fetch)
-# origin git@github.com:${user}/submarine.git (push)
-# upstream https://github.com/apache/submarine (fetch)
+# Check upstream/origin:
+# origin git@github.com:${USERNAME}/submarine.git (fetch)
+# origin git@github.com:${USERNAME}/submarine.git (push)
+# upstream git@github.com:apache/submarine.git (fetch)
# upstream no_push (push)
git remote -v
```
-### Step 3: Branch
+### Step3: Create a new Jira in Submarine project
+* New contributors need privilege to create JIRA issues. Please email kaihsun@apache.org with your Jira username. In addition, the email title should be "[New Submarine Contributor]".
+* Check [Jira issue tracker](https://issues.apache.org/jira/projects/SUBMARINE/issues/SUBMARINE-748?filter=allopenissues) for existing issues.
+* Create a new Jira issue in Submarine project. When the issue is created, a Jira number (eg. SUBMARINE-748) will be assigned to the issue automatically.
+
-Get your local master up to date:
+### Step4: Create a local branch for your contribution
```sh
-cd ${working_dir}/submarine
-git fetch upstream
+cd submarine
+
+# Make your local master up-to-date
git checkout master
+git fetch upstream
git rebase upstream/master
-```
-Branch from master:
-
-```sh
+# Create a new branch fro issue SUBMARINE-${jira_number}
git checkout -b SUBMARINE-${jira_number}
-```
-
-### Step 4: Develop
-
-#### Edit the code
-
-You can now edit the code on the `SUBMARINE-${jira_number}` branch.
-#### Test
-
-Build and run all tests:
-
-### Step 5: Keep your branch in sync
-
-```sh
-# While on your SUBMARINE-${jira_number} branch.
-git fetch upstream
-git rebase upstream/master
+# Example: git checkout -b SUBMARINE-748
```
-Please don't use `git pull` instead of the above `fetch`/`rebase`. `git pull` does a merge, which leaves merge commits. These make the commit history messy and violate the principle that commits ought to be individually understandable and useful (see below). You can also consider changing your `.git/config` file via `git config branch.autoSetupRebase` always to change the behavior of `git pull`.
-
-### Step 6: Commit
-
-Commit your changes.
-
+### Step5: Develop & Create commits
+* You can edit the code on the `SUBMARINE-${jira_number}` branch. (Coding Style: [Code Convention](#code-convention))
+* Create commits
```sh
-git commit
+git add ${edited files}
+git commit -m "SUBMARINE-${jira_number}. ${Commit Message}"
+# Example: git commit -m "SUBMARINE-748. Update Contributing guide"
```
-Likely you'll go back and edit/build/test further and then `commit --amend` in a few cycles.
-
-### Step 7: Push
-
-When the changes are ready to review (or you just want to create an offsite backup of your work), push your branch to your fork on `github.com`:
-
+### Step6: Syncing your local branch with upstream/master
```sh
-git push --set-upstream ${your_remote_name} SUBMARINE-${jira_number}
-```
-
-### Step 8: Create a pull request
-
-1. Visit your fork at `https://github.com/${user}/submarine`.
-2. Click the `Compare & Pull Request` button next to your `SUBMARINE-${jira_number}` branch.
-3. Fill in the required information in the PR template.
-
-#### Get a code review
-
-If your pull request (PR) is opened, it will be assigned to one or more reviewers. Those reviewers will do a thorough code review, looking at correctness, bugs, opportunities for improvement, documentation comments, and style.
-
-To address review comments, you should commit the changes to the same branch of the PR on your fork.
-
-#### Revert a commit
-
-In case you wish to revert a commit, follow the instructions below:
-
-> NOTE: If you have upstream write access, please refrain from using the Revert
-> button in the GitHub UI for creating the PR, because GitHub will create the
-> PR branch inside the main repository rather than inside your fork.
-
-Create a branch and synchronize it with the upstream:
-
-```sh
-# create a branch
-git checkout -b myrevert
-
-# sync the branch with upstream
+# On SUBMARINE-${jira_number} branch
git fetch upstream
git rebase upstream/master
-
-# SHA is the hash of the commit you wish to revert
-git revert SHA
```
-This creates a new commit reverting the change. Push this new commit to your remote:
+* Please do not use `git pull` to synchronize your local branch. Because `git pull` does a merge to create merged commits, these will make commit history messy.
+### Step7: Push your local branch to your personal fork
```sh
-git push ${your_remote_name} myrevert
+git push origin SUBMARINE-${jira_number}
```
-Create a PR based on this branch.
-
-#### Cherry pick a commit to a release branch
-
-In case you wish to cherry pick a commit to a release branch, follow the instructions below:
+### Step8: Check Travis-ci status of your personal fork
+* Visit `https://travis-ci.com/github/${USERNAME}/submarine`
+* Please make sure your new commits can pass all integration tests before creating a pull request.
-Create a branch and synchronize it with the upstream:
+### Step9: Create a pull request on github UI
+* Visit your fork at `https://github.com/${USERNAME}/submarine.git`
+* Click `Compare & Pull Request` button to create pull request.
+
-```sh
-# sync the branch with upstream.
-git fetch upstream
+#### Pull Request template
+* [Pull request template](https://github.com/apache/submarine/blob/bd7578cc28f8280f9170938d4469fcc965e24a89/.github/PULL_REQUEST_TEMPLATE)
+* Filling the template thoroughly can improve the speed of the review process. Example:
-# checkout the release branch.
-# ${release_branch_name} is the release branch you wish to cherry pick to.
-git checkout upstream/${release_branch_name}
-git checkout -b my-cherry-pick
+
-# cherry pick the commit to my-cherry-pick branch.
-# ${SHA} is the hash of the commit you wish to revert.
-git cherry-pick ${SHA}
+### Step10: Check Travis-ci status of your pull request in apache/submarine
+* Visit https://travis-ci.com/github/apache/submarine/pull_requests
+* Please make sure your pull request can pass all integration tests.
-# push this branch to your repo, file an PR based on this branch.
-git push --set-upstream ${your_remote_name} my-cherry-pick
-```
+### Step11: The Review Process
+* Anyone can be a reviewer and comment on the pull requests.
+* Reviewer can indicate that a patch looks suitable for merging with a comment such as: "Looks good", "LGTM", "+1". (PS: LGTM = Looks Good To Me)
+* At least one indication of suitability (e.g. "LGTM") from a committer is required to be merged.
+* A committer can then initiate lazy consensus ("Merge if there is no more discussion") after which the code can be merged after a particular time (usually 24 hours) if there are no more reviews.
+* Contributors can ping reviewers (including committers) by commenting 'Ready to review'.
-## Build
+### Step12: Address review comments
+* Push new commits to SUBMARINE-${jira_number} branch. The pull request will update automatically.
+* After you address all review comments, committers will merge the pull request.
-[Build From Code](../devDocs/BuildFromCode)
-## Continuous Integration
+### Code convention
+We are following Google Code style:
-Submarine project's CI system will collect information from pull request author's Travis-ci and display status in the pull request.
+* [Java style](https://google.github.io/styleguide/javaguide.html)
+* [Shell style](https://google.github.io/styleguide/shell.xml)
-Each individual contributor should setup Travis-ci for the fork before making a pull-request. Go to [https://travis-ci.org/profile](https://travis-ci.org/profile) and switch on 'submarine' repository.
+There are some plugins to format, lint your code in IDE (use [dev-support/maven-config/checkstyle.xml](hhttps://github.com/apache/submarine/blob/master/dev-support/maven-config/checkstyle.xml) as rules)
+* [Checkstyle plugin for Intellij](https://plugins.jetbrains.com/plugin/1065) ([Setting Guide](http://stackoverflow.com/questions/26955766/intellij-idea-checkstyle))
+* [Checkstyle plugin for Eclipse](http://eclipse-cs.sourceforge.net/#!/) ([Setting Guide](http://eclipse-cs.sourceforge.net/#!/project-setup))
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@submarine.apache.org
For additional commands, e-mail: dev-help@submarine.apache.org