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 matured enough, to up-port them on top of HEAD for review
• Once review accepted, push them in HEAD
• Rebase not yet accepted/too recent changes from releng/X.Y to releng/X.(Y+1) to keep them relevant for future HEAD inclusion

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

• Note: These steps are done only once for a given local git repository

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 branches looks 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 existing in origin repository:

$ git fetch origin
$ git checkout -t origin/10.0-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"

Get last remote changes 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

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

Merge last changes from upstream release branch

$ git merge upstream/releng/10.2 -m "Merge up to patch level p4 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

== Checkout a Private Tag ===

$ git checkout -t tags/v10.2.4.0

Get personal repository changes. For example to rebase changes made in 10.1 to 10.2

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

Start interactive rebase changes made in previous branch on top of the new one

$ git rebase -i --onto 10.1-next upstream/release/10.0.0 10.0-next

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

During the interactive rebase you have in opportunity to:

• Remove already accepted in upstream changes
• 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 to propose uptream

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

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

Checkout local work branch and get last remote 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. In this example, we use 'master' which correlates to the upstream HEAD.

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 Verisign sources

$ git pull –rebase $ git push origin HEAD