gitworkflow:triangularworkflow

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
gitworkflow:triangularworkflow [2015/09/14 15:44] – JulienCharbongitworkflow:triangularworkflow [2015/09/14 20:34] (current) – JulienCharbon
Line 1: Line 1:
 ====== Git Triangular Workflow ====== ====== Git Triangular Workflow ======
  
-This git workflow focuses on:+The main characteristics of this workflow are:
  
-  * Keeping in sync a %%FreeBSD%% release branch, e.g. releng/X.Y and not ''%%-CURRENT%%'' +  * Develop changes on top of %%FreeBSD%% release branch, e.g. ''%%releng/X.Y%%'' 
-  * Develop improvements/fixes on top of this release branch and publish them in a personal git repository +  * Publish these changes in a personal/corporate git repository for testing and use in production 
-  * Once these changes have been tested and matured enough, to up-port them on top of HEAD for review+  * 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   * 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+  * Rebase changes that have not yet been accepted to old ''%%releng/X.Y%%'' branch to new ''%%releng/X.(Y+1)%%'' branch
  
-====== Introduction ======+For experimented git users (i.e. users that already fell in every git pitfalls) this workflow is common sense, but might help some to start %%FreeBSD%% contributions with a straightforward workflow.
  
-This workflow assumes you use multiple repositories, at least:+{{gitworkflow/triangularworkflow/git-47.png}} 
 + 
 +====== Introduction ======
  
-origin repository:: Our own personal repository with full access, e.g. ''%%https://github.com/user/freebsd/%%''+This workflow assumes you use multiple repositories, i.e.:
  
-upstream repository:: The official %%FreeBSD%% repository with read-only access, e.g. ''%%https://github.com/freebsd/freebsd/%%''+  * **origin repository**: Our own personal/corporate repository with full access, e.g. ''%%https://github.com/user/freebsd/%%''
  
-  * **Main Rules** +  * **upstream repository**: The official %%FreeBSD%% repository with read-only access, e.g. ''%%https://github.com/freebsd/freebsd/%%''
-    * Changes coming from ''%%upstream%%'' are merged +
-    * Changes made in ''%%origin%%'' are rebased+
  
-====== Local Git Repository First Step ======+  * **Main workflow rules being** 
 +    * Changes coming from ''%%upstream%%'' repository are merged 
 +    * Changes developed in ''%%origin%%'' repository are rebased
  
-  * **Note**: These steps are done only once for a given local git repository+====== Local Git Repository First Steps ======
  
-Clone personal %%FreeBSD%% git repository+Clone personal %%FreeBSD%% git repository (can be empty at first)
  
 <code> <code>
Line 39: Line 41:
 </code> </code>
  
-  * **Note**: ''%%git fetch upstream%%'' command will take roughly 5/10 minutes depending on our internet connection+  * **Note**: ''%%$ git fetch upstream%%'' command will take roughly 5/10 minutes depending on our internet connection
  
-===== Origin Repository Branches =====+====== Origin Repository Branches ======
  
-Origin branches looks like:+Origin repository branches will look like:
  
 <code> <code>
Line 51: Line 53:
 10.1-next/ 10.1-next/
 10.2-next/ 10.2-next/
 +master
 </code> </code>
  
-The ''%%X.Y-next%%'' branches are where changes/fixes are added.  These branches are created from corresponding upstream release branches ''%%releng/X.Y/%%'' from [[/FreeBSD upstream Git repos|https://github.com/freebsd/freebsd]].  See below how they are created.+The ''%%X.Y-next%%'' branches are where changes/fixes are developed.  These branches are created from corresponding upstream release branches ''%%releng/X.Y/%%'' from upstream repository.  ''%%master%%'' branch is just ''%%CURRENT%%'', and used for review creation.  See below how they are created.
  
-====== Create X.Y-next Branch ======+====== Create a X.Y-next Branch and Publish it ======
  
 Get last upstream changes Get last upstream changes
Line 75: Line 78:
 </code> </code>
  
-==== Checkout a X.Y-next Branch ====+===== Checkout a X.Y-next Branch =====
  
-If the ''%%X.Y-next%%'' is already existing in origin repository:+If the ''%%X.Y-next%%'' is already present in origin repository:
  
 <code> <code>
 $ git fetch origin $ git fetch origin
-$ git checkout -t origin/10.0-next+$ git checkout -t origin/10.2-next
 </code> </code>
  
-===== Make and Publish Custom Changes =====+====== Create master Branch and Publish it ======
  
-Checkout local work branch and get last remote changes+Get last upstream changes 
 + 
 +<code> 
 +$ git fetch upstream 
 +</code> 
 + 
 +Create new ''%%master%%'' branch from corresponding ''%%upstream/master%%'' ''%%CURRENT%%'' branch 
 + 
 +<code> 
 +$ git checkout -t upstream/master 
 +</code> 
 + 
 +Publish ''%%master%%'' branch to origin repository 
 + 
 +<code> 
 +$ git push origin HEAD 
 +</code> 
 + 
 +====== Make and Publish Custom Changes in Origin Repository ====== 
 + 
 +Checkout ''%%X.Y-next%%'' branch and get last origin changes
  
 <code> <code>
Line 93: Line 116:
 </code> </code>
  
-Make source code changes and locally commit them+Make changes and locally commit them
  
 <code> <code>
Line 99: Line 122:
 # Hack, test, hack # Hack, test, hack
 $ git add foo/bar.c $ git add foo/bar.c
-$ git commit -m "[bz#42]: Fix this issue"+$ git commit -m "[bz#42]: Fix this issue/Improve performances"
 </code> </code>
  
-Get last remote changes and publish yours+Once tested, rebase on top of last origin repository changes, and publish
  
 <code> <code>
Line 109: Line 132:
 </code> </code>
  
-==== Merge Errata/Security Patches from Upstream ====+====== Merge Errata/Security Patches from Upstream ======
  
-  * **Note**: No Operating System is without sins, thus you need to merge Errata/Security patches from corresponding release branch+  * **Note**: No Operating System is without sins, thus you need to merge Errata/Security patches from corresponding release branch in a timely manner
  
-Checkout local work branch and get last origin changes+Checkout ''%%X.Y-next%%'' branch and get last origin changes
  
 <code> <code>
Line 120: Line 143:
 </code> </code>
  
-Get last upstream changes and check the log+Get last upstream changes and check the log for Errata/Security details
  
 <code> <code>
Line 127: Line 150:
 </code> </code>
  
-Merge last changes from upstream release branch+Merge last upstream changes from corresponding release branch
  
 <code> <code>
-$ git merge upstream/releng/10.2 -m "Merge up to patch level p4 from releng/10.2 into 10.2-next"+$ git merge upstream/releng/10.2 -m "Merge Errata/Security from releng/10.2 into 10.2-next"
 </code> </code>
  
-Resolve conflicts if any, than check final result+Resolve conflicts if any, than check the result
  
 <code> <code>
Line 139: Line 162:
 </code> </code>
  
-Publish merged upstream changes in orign+Publish merged upstream changes in origin
  
 <code> <code>
Line 145: Line 168:
 </code> </code>
  
-Next you can update %%FreeBSD%% release number in ''%%release/Makefile%%'' and create your private tag for release purpose.  See below.+Next you can update %%FreeBSD%% release number in ''%%release/Makefile%%'' and create your own tag for release/testing purpose.  See below.
  
-==== Create Private Tag and Publish it ====+===== Create Tag and Publish it =====
  
 <code> <code>
Line 154: Line 177:
 </code> </code>
  
-%%=%%= Checkout a Private Tag ===+===== Checkout a Tag =====
  
 <code> <code>
Line 160: Line 183:
 </code> </code>
  
-==== Rebase Custom Changes onto a New Release Branch ====+====== Rebase Custom Changes onto a New Release Branch ======
  
-Get personal repository changes.  For example to rebase changes made in 10.1 to 10.2+Get all origin and upstream repositories changes.  For example to rebase your changes made in ''%%10.1-next%%'' to ''%%10.2-next%%''
  
 <code> <code>
Line 173: Line 196:
 </code> </code>
  
-Start interactive rebase changes made in previous branch on top of the new one+Start an interactive rebase for all changes made in ''%%X.Y%%'' to ''%%X.(Y+1)%%''
  
 <code> <code>
-$ git rebase -i --onto 10.1-next upstream/release/10.0.0 10.0-next+$ git rebase -i --onto 10.2-next upstream/release/10.1.0 10.1-next
 </code> </code>
  
-  * **Note**: [[/Interactive rebase|https://help.github.com/articles/interactive-rebase]] documentation+  * **Note**: See [[/Interactive rebase|https://help.github.com/articles/interactive-rebase]] documentation 
 + 
 +  * **Note**: Rebase is smart/dumb enough to skip all already accepted included the new ''%%X.(Y+1)-next%%'' branch 
 + 
 +  * **Note**: Rebase will skip all Errata/Security merge commits, this is the default behaviour and that you actually want as all Errata/Security changes are already in ''%%X.(Y+1)-next%%'' branch by definition of a %%FreeBSD%% release branch
  
 During the interactive rebase you have in opportunity to: During the interactive rebase you have in opportunity to:
-  * Remove already accepted in upstream changes+
   * Remove now irrelevant changes   * Remove now irrelevant changes
-  * Squash (flatten) changes related to same fix/feature implementation in only one commit:+  * Squash changes related to same fix/feature implementation in only one commit:
     * Make things easier for future rebases     * Make things easier for future rebases
     * Make history easier to read     * Make history easier to read
-    * Cleaner patch to propose uptream+    * Cleaner patch for upstream proposal 
 +  * Re-order your changes 
 + 
 +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 
 + 
 +====== Advantages/Disadvantages ====== 
 + 
 +===== Advantages ===== 
 + 
 +  * Use of last release branch for stability 
 +  * Custom changes/fixed are used/tested in production before review 
 +  * No need to wait upstream acceptation before enjoying fixes and improvements 
 +  * These changes make great candidates for MFC (Merge From Current) once accepted in CURRENT 
 +  * Keep patches clean over new release branches 
 +  * The origin repository includes only the branches you are working on/you care about.  It is not a full complete fork of the upstream repository 
 +  * Interface nicely with %%FreeBSD%% reviews (Phabricator/arc) (see below) 
 + 
 +===== Disadvantages ===== 
 + 
 +  * Development is not done in CURRENT 
 +  * Patches are “up-ported” to CURRENT once tested/have matured enough 
 +  * Patches are in two branches until accepted: 
 +    * ''%%X.Y-next%%'' (Release branch) 
 +    * ''%%feature-review%%'' (Branch for upstream review) (see below) 
 + 
 +====== More Usages Examples ====== 
 + 
 +===== Creating a Review for CURRENT from X.Y-next branch ===== 
 + 
 +Checkout last changes from ''%%upstream/master%%'' 
 + 
 +<code> 
 +$ git fetch upstream 
 +$ git checkout master 
 +$ git pull --rebase 
 +</code> 
 + 
 +Create review branch 
 + 
 +<code> 
 +$ git checkout -b feature-foo-review master 
 +$ git push -u origin HEAD # It creates the base commit for the review 
 +</code> 
 + 
 +Cherry-pick changes related to "feature foo" from ''%%X.Y-next%%'' branch 
 + 
 +<code> 
 +$ git log origin/10.2-next # Note SHA strings of desired commits 
 +$ git cherry-pick $SHA1 $SHA2 
 +</code> 
 + 
 +and create the review 
 + 
 +<code> 
 +$ arc which # Check that commit $SHA1 and $SHA2 will be part of the review 
 +$ arc diff --create # Create review D1234 
 +</code> 
 + 
 +==== Update your Review ==== 
 + 
 +If during review changes are required, local commit the desired changes and include them in the review 
 + 
 +<code> 
 +$ vim foo/bar.c 
 +# Hack, test, hack 
 +$ git add foo/bar.c 
 +$ git commit -m "Address comments from review D1234" 
 +$ arc which # Check that all desired commits are part of the review 
 +$ arc diff --update D1234  
 +</code> 
 + 
 +==== Rebase your Review on more Recent CURRENT ==== 
 + 
 +If the review takes a while, you can rebase your changes on top of the current master and update the review. 
 + 
 +First get last upstream changes 
 + 
 +<code> 
 +$ git checkout master 
 +$ git pull --rebase 
 +</code> 
 + 
 +Then rebase your changes on it 
 + 
 +<code> 
 +$ git checkout feature-foo-review 
 +$ git rebase master 
 +</code> 
 + 
 +And update the review 
 + 
 +<code> 
 +$ 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 
 +</code>
  
-This is different from classical SVN vendor model merge workflow, here we want our changes always on top of the last release: +===== Cherry-pick Specific Commits from Upstream =====
-  * 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+
  
-===== Fetch and cherry pick specific commits from 'upstream' =====+Note: Sometimes You might want to get a change from ''%%CURRENT%%'' to your ''%%X.Y-next%%'' branch
  
-Checkout local work branch and get last remote changes+Checkout ''%%X.Y-next%%'' branch and get last origin changes
  
 <code> <code>
Line 202: Line 324:
 </code> </code>
  
-Get last upstream changes and check the log for the SHA of the commit(s) to cherry-pick+Get last upstream changes and check the log for the SHA of the desired commit(s) to cherry-pick
  
 <code> <code>
Line 209: Line 331:
 </code> </code>
  
-  * **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 desired changes from ''%%upstream/master%%''
- +
-Cherry-pick changes from ''%%upstream/master%%''+
  
 <code> <code>
-$ git cherry-pick $SHA+$ git cherry-pick SHA
 </code> </code>
  
-  * **Note**: Where $SHA is the SHA string of the commit to cherry-pick+  * **Note**: Where SHA is the SHA string of the commit to cherry-pick
  
-Resolve conflicts and check commit merge diff+Resolve conflicts and check result
  
 +<code>
 $ git log -p $ git log -p
 +</code>
  
-Publish cherry-picked upstream changes to Verisign sources+Publish cherry-picked changes to origin repository
  
 +<code>
 $ git pull --rebase $ git pull --rebase
 $ git push origin HEAD $ git push origin HEAD
 +</code>
  
  • gitworkflow/triangularworkflow.1442245495.txt.gz
  • Last modified: 2015/09/14 15:44
  • by JulienCharbon