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 16:36] – 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 have matured enough, 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 in review/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
  
-For experimented git users this is only common sense, but might help you to start %%FreeBSD%% contributions with a simple git workflow.+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.
  
-{{gitworkflow/triangularworkflow/git-47.png?linkonly|git-47.png}}+{{gitworkflow/triangularworkflow/git-47.png}}
  
 ====== Introduction ====== ====== Introduction ======
  
-This workflow assumes you use multiple repositories, at least:+This workflow assumes you use multiple repositories, i.e.:
  
-origin repository:: Our own personal repository with full access, e.g. ''%%https://github.com/user/freebsd/%%''+  * **origin repository**: Our own personal/corporate 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/%%''+  * **upstream repository**: The official %%FreeBSD%% repository with read-only access, e.g. ''%%https://github.com/freebsd/freebsd/%%''
  
-  * **Main Rules** +  * **Main workflow rules being** 
-    * Changes coming from ''%%upstream%%'' are merged +    * Changes coming from ''%%upstream%%'' repository are merged 
-    * Changes made in ''%%origin%%'' are rebased+    * Changes developed in ''%%origin%%'' repository are rebased
  
 ====== Local Git Repository First Steps ====== ====== Local Git Repository First Steps ======
  
-Clone personal %%FreeBSD%% git repository+Clone personal %%FreeBSD%% git repository (can be empty at first)
  
 <code> <code>
Line 41: 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 ======
Line 53: 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 a X.Y-next Branch ======+====== Create a X.Y-next Branch and Publish it ======
  
 Get last upstream changes Get last upstream changes
Line 79: Line 80:
 ===== Checkout a X.Y-next Branch ===== ===== Checkout a X.Y-next Branch =====
  
-If the ''%%X.Y-next%%'' is already created in origin repository:+If the ''%%X.Y-next%%'' is already present in origin repository:
  
 <code> <code>
Line 86: Line 87:
 </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 95: Line 116:
 </code> </code>
  
-Make source code changes and locally commit them+Make changes and locally commit them
  
 <code> <code>
Line 101: 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>
  
-Once tested, rebase on top of last origin changes if any, and publish yours+Once tested, rebase on top of last origin repository changes, and publish
  
 <code> <code>
Line 113: Line 134:
 ====== 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 122: Line 143:
 </code> </code>
  
-Get last upstream changes and check the log for Errata/Security information+Get last upstream changes and check the log for Errata/Security details
  
 <code> <code>
Line 129: Line 150:
 </code> </code>
  
-Merge last changes from upstream release branch+Merge last upstream changes from corresponding release branch
  
 <code> <code>
Line 135: Line 156:
 </code> </code>
  
-Resolve conflicts if any, than check final result+Resolve conflicts if any, than check the result
  
 <code> <code>
Line 141: Line 162:
 </code> </code>
  
-Publish merged upstream changes in orign+Publish merged upstream changes in origin
  
 <code> <code>
Line 147: 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 156: Line 177:
 </code> </code>
  
-===== Checkout a Private Tag =====+===== Checkout a Tag =====
  
 <code> <code>
Line 164: Line 185:
 ====== Rebase Custom Changes onto a New Release Branch ====== ====== Rebase Custom Changes onto a New Release Branch ======
  
-Get all origin and upstream repositories changes.  For example to rebase changes made in 10.1-next to 10.2-next+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 175: Line 196:
 </code> </code>
  
-Start an interactive rebase for all changes made in X.Y to X.(Y+1)+Start an interactive rebase for all changes made in ''%%X.Y%%'' to ''%%X.(Y+1)%%''
  
 <code> <code>
Line 183: Line 204:
   * **Note**: See [[/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 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 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, 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+  * **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 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 for upstream proposal     * 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: 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 appear clearly
-  * Custom changes will be on top the last release version, and be easier to propose them to upstream, and for future rebases+  * Custom changes will be on top the last release version, and be easier to propose them to upstream
  
 ====== Advantages/Disadvantages ====== ====== Advantages/Disadvantages ======
  
-====== More Usages examples ======+===== 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>
  
 ===== Cherry-pick Specific Commits from Upstream ===== ===== Cherry-pick Specific Commits from Upstream =====
  
-Note: You might want sometimes to MFC a change from ''%%CURRENT%%'' to you ''%%X.Y-next%%'' branch+Note: Sometimes You might want to get a change from ''%%CURRENT%%'' to your ''%%X.Y-next%%'' branch
  
-Checkout local work branch and get last origin changes+Checkout ''%%X.Y-next%%'' branch and get last origin changes
  
 <code> <code>
Line 214: 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 221: Line 331:
 </code> </code>
  
-  * **Note**: One may select any branch from which to cherry pick specific commits. +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> <code>
Line 237: Line 345:
 </code> </code>
  
-Publish cherry-picked upstream changes to origin repository+Publish cherry-picked changes to origin repository
  
 <code> <code>
  • gitworkflow/triangularworkflow.1442248561.txt.gz
  • Last modified: 2015/09/14 16:36
  • by JulienCharbon