Git Forking Workflow

Git Forking Workflow

Table of Contents

1. Overview
2. Setup
3. Development
4. Release
   1. Release to staging
   2. Release to production

Overview

The main advantage of the forking workflow is to keep the main repo safe and clean. Safe as direct pushes to the main repo are disallowed. Only pull requests can be merged by team members into the main repo. Clean as the main repo keeps only a single-thread of history on the master branch free of noises.

Typically the main repo hooks up directly to deployment. On the main repo, the following are expected:

1. The master branch
2. The release branch (and/or release tags)
3. Hot patches made on the release branch and merged back to the master branch

Whereas a fork focuses on development:

1. Master branch in sync with that of the main repo
2. Dev (or feature) branches

Here is what I call "the git triangle":

Setup

Make "Read" the default permission for the organization

This is optional. On the organization's page, click the "Settings" tab, then "Member privileges". Set the default repository permission to "Read".

Restrict who can push to the branch

On the repo's page, click "Settings", then "Branches". Choose the (master) branch to protect. Check "Restrict who can push to this branch" and save the changes.

Development

Here are repo names used in the description of the workflows:

• main: the main repo (note this is often called upstream)
• origin: the developer's fork

Sync with the main repo

1. git checkout master -- check out the local master branch
2. git pull --rebase main master -- update the local master branch with that of the main repo, rebase to avoid a merge commit which is unnecessary here
3. git push origin master -- update the fork's master branch

Develop on a dev branch

Note it recommends to always create a new branch for new development work. That is to say, do not reuse branches for development. The main repo may rewrite development history, for example, by squash merging commits. Syncing up with the main repo after merge creates "shadow" commits on the development branch. To solve the problem always sync up on the master branch. Development is always done on a newly created development branch. The new branch is always merged into the main' master by pull requests. It can be deleted after the work is done (merged).

1. git checkout -b dev -- create a new dev branch of the local master and check it out
2. Development work
3. Send out a pull request on this dev branch
4. More development work
5. Can be deleted after the pull request is merged and eventually deployed
6. git checkout master
7. git branch -d dev
8. git push origin :dev

Release

Release to staging

The idea is that the master branch is hooked to the integration stack. Commits to the master branch are automatically deployed to the integration stack and are continuously tested.

Whereas the release (or staging) branch is hooked to the staging stack. Specific commits on the master branch can be hand-picked to merge into the release branch. They are automatically deployed to the staging stack as release candidates.

Merging to release is fast-forward only git merge --ff-only <commit>.

A release branch makes it easier to receive hot patches. Patch is made on the release branch and merged back to the master branch.

On a machine devoted to managing releases, or on a local dev box:

1. Manage the projects' source in the ~/Workspace folder, the same as local development, but name the project folder <project>-staging:

$ ls -1 ~/Workspace
  <project1>-staging
  <project2>-staging
  ...

2. For any project, the remote is the "main" remote (i.e. the team's remote):

$ git remote -v
  main  https://<usr>@github.com/<team>/<project>.git (fetch)
  main  https://<usr>@github.com/<team>/<project>.git (push)

3. It has the master branch and the staging branch and the local branches are set to track respective remote branches:

$ git branch -a
    master
  * staging
    remotes/main/master
    remotes/main/staging

4. The steps to release is as following:

# Fetch from remote
$ git fetch main

# Update the local master branch
$ git checkout master
$ git merge --ff-only main/master

# Update the local staging branch
$ git checkout staging
$ git merge --ff-only master

# Push to remote staging
$ git push main staging

When updating the local staging branch, can pick a particular commit:

$ git merge --ff-only 27df7f3

Release to production

Releasing to production usually do not build the source any more. Unlike staging, there is no production branch. Production deployment deploys the build artifact.

Release to Maven central

Assuming you have created account with OSSRH and they accept published artifacts from you. Assuming you have set up Maven (or Gradle) and Travis CI for that.

One action of releasing to the staging branch is that Travis CI will upload the staging artifacts to OSSRH. Read the Travis CI log and make sure the artifacts have been successfully uploaded.

Log in to OSSRH. Check the staging repositories on the Nexus Repository Manager. One of the staging bundles should be yours. Check its content and make sure it is good. Click the "Close" button. This will trigger OSS for a sanity check. If the check passes, the "Release" button will be enabled. Click the "Release" button will release the code to Maven central.

Resources

1. git-merge -- must read