This git workflow focuses on:

• Keeping in sync a FreeBSD release branch, e.g. releng/X.Y and not -CURRENT
• Develop improvements/fixes on top of this release branch and publish them in a personal git repository
• Once these changes have been tested and have matured enough, up-port them on top of HEAD for review
• Once review accepted, push them in HEAD
• Rebase in review/too recent changes from releng/X.Y to releng/X.(Y+1) to keep them relevant for future HEAD inclusion

For experimented git users this is only common sense, but might help you to start FreeBSD contributions with a simple git workflow.

This workflow assumes you use multiple repositories, at least:

origin repository:: Our own personal repository with full access, e.g. https://github.com/user/freebsd/

upstream repository:: The official FreeBSD repository with read-only access, e.g. https://github.com/freebsd/freebsd/

• Main Rules
  • Changes coming from upstream are merged
  • Changes made in origin are rebased

Clone personal FreeBSD git repository

$ git clone git@github.com:user/freebsd.git
$ cd freebsd/

Add FreeBSD upstream as remote repository and fetch changes

$ git remote add upstream git@github.com:freebsd/freebsd.git
$ git fetch upstream

• Note: $ git fetch upstream command will take roughly 5/10 minutes depending on our internet connection

Origin repository branches will look like:

8.3-next/
8.4-next/
10.0-next/
10.1-next/
10.2-next/

The X.Y-next branches are where changes/fixes are added. These branches are created from corresponding upstream release branches releng/X.Y/ from https://github.com/freebsd/freebsd. See below how they are created.

Get last upstream changes

$ git fetch upstream

Create new X.Y-next branch from corresponding upstream/releng/X.Y release branch

$ git checkout -b 10.2-next upstream/releng/10.2

Publish branch to origin repository

$ git push -u origin 10.2-next

If the X.Y-next is already created in origin repository:

$ git fetch origin
$ git checkout -t origin/10.2-next

Checkout local work branch and get last remote changes

$ git checkout 10.2-next
$ git pull --rebase

Make source code changes and locally commit them

$ vim foo/bar.c
# Hack, test, hack
$ git add foo/bar.c
$ git commit -m "[bz#42]: Fix this issue"

Once tested, rebase on top of last origin changes if any, and publish yours

$ git pull --rebase
$ git push origin HEAD

• Note: No Operating System is without sins, thus you need to merge Errata/Security patches from corresponding release branch

Checkout local work branch and get last origin changes

$ git checkout 10.2-next
$ git pull --rebase

Get last upstream changes and check the log for Errata/Security information

$ git fetch upstream
$ git log upstream/releng/10.2

Merge last changes from upstream release branch

$ git merge upstream/releng/10.2 -m "Merge Errata/Security from releng/10.2 into 10.2-next"

Resolve conflicts if any, than check final result

$ git log -p -m --first-parent

Publish merged upstream changes in orign

$ git push origin HEAD

Next you can update FreeBSD release number in release/Makefile and create your private tag for release purpose. See below.

$ git tag -a v10.2.4.0 -m "My FreeBSD Release 10.2.4.0"
$ git push --tags

$ git checkout -t tags/v10.2.4.0

Get all origin and upstream repositories changes. For example to rebase changes made in 10.1-next to 10.2-next

$ git fetch upstream
$ git fetch origin
$ git checkout 10.1-next
$ git pull --rebase
$ git checkout 10.2-next
$ git pull --rebase

Start an interactive rebase for all changes made in X.Y to X.(Y+1)

$ git rebase -i --onto 10.2-next upstream/release/10.1.0 10.1-next

• Note: See https://help.github.com/articles/interactive-rebase documentation

• Note: Rebase is smart enough to skip all already accepted changes the new X.(Y+1)-next branch, i.e. git rebase skips all commit that introduce an exact same change

• Note: Rebase will skip all Errata/Security merge, this is the default git rebase behaviour and that you actually want as all Errata/Security changes you want are already in X.(Y+1)-next branch by definition of a FreeBSD release branch

During the interactive rebase you have in opportunity to:

• Remove now irrelevant changes
• Squash (flatten) changes related to same fix/feature implementation in only one commit:
  • Make things easier for future rebases
  • Make history easier to read
  • Cleaner patch for upstream proposal

This is different workflow than the classical SVN vendor model merge workflow, here we want to see our changes always on top of the last release branch:

• Custom changes will appear clearly
• Custom changes will be on top the last release version, and be easier to propose them to upstream, and for future rebases

• Use last release branch
• Custom changes/fixed are used/tested in production first
• No need to wait upstream for fixes and improvements
• These changes make great candidates for MFC (Merge From Current) once accepted in CURRENT
• Keep patches clean over releases
• Interface nicely with FreeBSD reviews (Phabricator)

• Development is not done in CURRENT first
• Patches are “up-ported” to HEAD once tested/have matured enough
• Patches are in two branches until accepted:
  • X.Y-next (Release Branche)
  • feature-review (Branch for Patch Proposed to Upstream)

Note: You might want sometimes to MFC a change from CURRENT to you X.Y-next branch

Checkout local work branch and get last origin changes

$ git checkout 10.2-next
$ git pull --rebase

Get last upstream changes and check the log for the SHA of the commit(s) to cherry-pick

$ git fetch upstream
$ git log upstream/master

• Note: One may select any branch from which to cherry pick specific commits.

Cherry-pick changes from upstream/master

$ git cherry-pick $SHA

• Note: Where $SHA is the SHA string of the commit to cherry-pick

Resolve conflicts and check commit merge diff

$ git log -p

Publish cherry-picked upstream changes to origin repository

$ git pull --rebase
$ git push origin HEAD

Checkout last changes from upstream/master

$ git fetch upstream
$ git co -b master upstream/master
$ git pull --rebase

Create review branch, and put your changes related to “feature foo” in it, and create the review

$ git co -b feature-foo-review master
$ git push -u origin HEAD # It creates the base commit for the review
$ git log origin/10.2-next # Get SHA strings of desired commits
$ git cherry-pick $SHA1 $SHA2
$ arc which # Check that commit $SHA1 and $SHA2 will be part of the review
$ arc diff --create

If during review changes are required, local commit the desired changes and include them in the review

$ vim foo/bar.c
# Hack, test, hack
$ git add foo/bar.c
$ git commit -m "Address comment #X from review D1234"
$ arc which # Check that all desired commits are part of the review
$ arc diff --update D1234 

If the review takes a while, you can rebase your changes on top of the current master and update the review.

First get last master changes

$ git co master
$ git pull --rebase

Then rebase your changes on it

$ git co feature-foo-review
$ git rebase master
$ git push origin master:feature-foo-review # Update the review base commit
$ arc which # Check that the review includes all desired commit changes, and only them
$ arc diff --update D1234