Apache SystemML Committer Git Guide

systemml_committer_guide.md

SystemML Git Guide

Setup Git repo locally

• Fork Apache SystemML to your personal GitHub account by browsing to [https://github.com/apache/incubator-systemml] and clicking "Fork".
• Clone your personal GitHub fork of Apache SystemML:
  • git clone git@github.com:USERNAME/incubator-systemml.git // assuming the use of SSH keys with GitHub
• Add GitHub (read-only mirror) and Apache-owned (committer writeable) Git repositories as remotes:
  • cd incubator-systemml
  • git remote add apache-github https://github.com/apache/incubator-systemml.git
  • git remote add apache https://git-wip-us.apache.org/repos/asf/incubator-systemml.git
• Add a Git alias for checking out GitHub pull requests locally:

  • Install alias globally by placing the following in ~/.gitconfig:

    [alias]
    pr = "!f() { git fetch ${2:-apache-github} pull/$1/head:pr-$1 && git checkout pr-$1; }; f"
    

  • Look at pull request on GitHub to determine the pull request number, indicated as "#4", for example.

  • Checkout out locally:

    • git pr 4

PR flow

• Create local branch for feature(s):
  • git checkout -b SYSML-####-My_Awesome_Feature
• Make commits on SYSML-####-My_Awesome_Feature branch.
• Push the SYSML-####-My_Awesome_Feature branch to your personal GitHub fork of SystemML:
  • git checkout SYSML-####-My_Awesome_Feature
  • First push of this branch:
    • git push --set-upstream origin SYSML-####-My_Awesome_Feature
  • Future pushes of this branch:
    • git push
• Open a new pull request by browsing to the SYSML-####-My_Awesome_Feature branch on your personal GitHub fork of SystemML and clicking "New pull request".

Merging (manually) without merge commits

• Squash commits into a single commit by rebasing:
  • git rebase -i HEAD~N, where N is the number of commits made on this PR branch.
  • Select pick for the first commit created, and select squash for all others.
  • Once completed, git log should show only one commit.
• Update your local SYSML-####-My_Awesome_Feature branch with the latest commits in the Apache repo by rebasing:
  • git checkout SYSML-####-My_Awesome_Feature
  • git pull --rebase apache master
• Edit the commit message, completed with updated dates:
  • git commit --amend --date="$(date +%s)"
  • Add a single-line title at the top.
  • Adjust the rest of the message as needed.
  • Add the phrase "Closes #M." to the end of a commit message, where M is the GitHub pull request number.
    • When the commit is eventually pushed to Apache, GitHub will automatically close pull request M, and the commit will contain a link to that pull request.
• Update your local master branch with the latest commits in the Apache repo:
  • git checkout master
  • git pull apache master
• Move the commit from your local SYSML-####-My_Awesome_Feature branch to the local master branch. Note: This will not create merge commits since both branches are fully updated from the Apache repo.
  • git checkout master
  • git merge SYSML-####-My_Awesome_Feature
    • Note: This should result in a "fast-forward" merge.
• Double-check on differences:
  • git diff apache/master.. for code changes.
  • git log apache/master.. for commit differences.
• Push to your GitHub repo (to check for correctness):
  • git push
  • git subtree push --prefix docs/ origin gh-pages for doc updates (git push origin --delete gh-pages to delete).
• Push to the Apache repo:
  • git push apache master
  • git subtree push --prefix docs/ apache gh-pages for doc updates.

Merging (script)

• WIP