Skip to main content
Version: master 🏃

How To Contribute to Submarine

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

Preface​

  • Apache Submarine is an Apache 2.0 License Software. Contributing to Submarine means you agree to the Apache 2.0 License.
  • Please read Code of Conduct carefully.
  • The document How It Works can help you understand Apache Software Foundation further.

Build Submarine​

Creating patches​

Submarine follows Fork & Pull model.

Step1: Fork apache/submarine github repository (first time)​

Step2: Clone the Submarine to your local machine​

# 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

# 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

Step3: Create a new Jira in Submarine project​

  • New contributors need privilege to create JIRA issues. Public signup for Apache Jira is disabled, we need to go to Apache Self serve sign up page to request an account.
  • After Jira account created, check Jira issue tracker 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. jira_number_example

Step4: Create a local branch for your contribution​

cd submarine

# Make your local master up-to-date
git checkout master
git fetch upstream 
git rebase upstream/master

# Create a new branch fro issue SUBMARINE-${jira_number}
git checkout -b SUBMARINE-${jira_number}

# Example: git checkout -b SUBMARINE-748

Step5: Develop & Create commits​

  • You can edit the code on the SUBMARINE-${jira_number} branch. (Coding Style: Code Convention)
  • Create commits
git add ${edited files}
git commit -m "SUBMARINE-${jira_number}. ${Commit Message}"
# Example: git commit -m "SUBMARINE-748. Update Contributing guide"

Step6: Syncing your local branch with upstream/master​

# On SUBMARINE-${jira_number} branch
git fetch upstream
git rebase upstream/master
  • 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​

git push origin SUBMARINE-${jira_number}

Step8: Check GitHub Actions status of your personal commit​

  • Visit https://github.com/${USERNAME}/submarine/actions
  • Please make sure your new commits can pass all workflows before creating a pull request.

check_ci_pass

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

Pull Request template​

  • Pull request template
  • Filling the template thoroughly can improve the speed of the review process. Example:

pull_request_template_example

Step10: Check GitHub Actions status of your pull request in apache/submarine​

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

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.

Code convention​

We are following Google Code style:

There are some plugins to format, lint your code in IDE (use dev-support/maven-config/checkstyle.xml as rules)