Difference between revisions of "Documentation/Nightly/Developers/ProjectForks"

From Slicer Wiki
Jump to: navigation, search
 
(One intermediate revision by the same user not shown)
Line 68: Line 68:
  
 
* If there is a long list of changes return by <code>git shortlog</code>, make sure to copy the full list. Before the list, consider also adding a short summary of the "interesting" changes. For example, see [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=25068 r25068]
 
* If there is a long list of changes return by <code>git shortlog</code>, make sure to copy the full list. Before the list, consider also adding a short summary of the "interesting" changes. For example, see [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=25068 r25068]
 +
 +
== FAQ ==
 +
 +
=== How to create the "slicer-" branch from a topic being contributed upstream ?  ===
 +
 +
Assuming the official repository was cloned and a <tt>topic</tt> with custom changes is already checked out.
 +
 +
1. Create the `slicer-` branch
 +
 +
# Extract version using git describe
 +
XYZ=$(git describe --tags | cut -d"-" -f1)
 +
echo "XYZ [${XYZ}]"
 +
 +
COMMON_SHA=$(git merge-base origin/master HEAD)
 +
COMMON_SHA=$(git show -s --format=%h ${COMMON_SHA})
 +
echo "COMMON_SHA [${COMMON_SHA}]"
 +
 +
DATE=$(git show -s --format=%ci ${COMMON_SHA} | cut -d" " -f1)
 +
echo "DATE [${DATE}]"
 +
 +
BRANCH_NAME=slicer-${XYZ}-${DATE}-${COMMON_SHA}
 +
echo "BRANCH_NAME [${BRANCH_NAME}]"
 +
 +
git checkout -b ${BRANCH_NAME}
 +
 +
 +
2. Add slicer remote
 +
 +
git remote add slicer git@github.com:Slicer/SimpleITK
 +
 +
3. Publish branch
 +
 +
git push slicer $BRANCH_NAME

Latest revision as of 16:08, 8 March 2018

Home < Documentation < Nightly < Developers < ProjectForks

Overview

While Slicer specific patches related to dependent project (i.e. VTK) are integrated upstream, it is not uncommon to build Slicer against a Slicer specific fork of the project.

For example: https://github.com/Slicer/VTK


Naming convention for Slicer fork branches

Patches for tagged release

For each version of the project requiring some specific patches, a branch following that convention will be created: slicer-vX.Y.Z-YEAR-MONTH-DAY where

  • X.Y.Z corresponds to the version of the fork project
  • YEAR-MONTH-DAY corresponds to the date of the last official commit of the fork project.

For example, in case of the Slicer/VTK fork, the branch slicer-v6.2.0-2015-03-02 has been created.

Patches for development branch

In this case, since there is no tag associated with the branch, the Slicer specific patch should be added to a branch named using the date of the commit parent of the Slicer branch: slicer-vX.Y-YEAR-MONTH-DAY-REV where

  • X.Y corresponds to the fork release
  • REV corresponds to either the first 7 chars of git hash or SVN revision (for example r1234)
  • YEAR-MONTH-DAY corresponds to the date of the last official commit of the fork project

For example: slicer-v6.2.0-2015-02-24-70bad0e

Adding patches to the fork

When adding new patches to the fork, prefer direct commits or cherry-picked commits over merge commits. Avoiding merge commits makes it easier to rebase the fork against a new upstream revision.

Commit message

Title and Content

The following command should be used to list changes:

git shortlog sha_before..sha_after --no-merges

where sha_before and sha_after are the first seven charachers of the SHA.

Here is an example of commit updating External_VTKv6.cmake in Slicer:

ENH: Update VTK to handle default values for array parameters in python
    
Without this commit, one must specify parameters like (,int array[3]=0) when
the method is called from python.

$ git shortlog 1c30cb0..4b9957b --no-merges
David Gobbi (2):
      Fix wrapping pointer parameters with default value 0.
      Handle default values for array parameters in python.

Source: r25160

Caveats

  • For the commit title, prefer something like ENH: Update VTK to ... instead of ENH: Update VTK git tag to ...
  • If there is only one commit in the update, it is reasonable to copy the message. For example, see r24693.
  • If the copied message reference the sha1 of its project (e.g VTK), change it to this form org/proj@sha. For example, see r24693.
  • If there is a long list of changes return by git shortlog, make sure to copy the full list. Before the list, consider also adding a short summary of the "interesting" changes. For example, see r25068

FAQ

How to create the "slicer-" branch from a topic being contributed upstream ?

Assuming the official repository was cloned and a topic with custom changes is already checked out.

1. Create the `slicer-` branch

# Extract version using git describe
XYZ=$(git describe --tags | cut -d"-" -f1)
echo "XYZ [${XYZ}]"

COMMON_SHA=$(git merge-base origin/master HEAD)
COMMON_SHA=$(git show -s --format=%h ${COMMON_SHA})
echo "COMMON_SHA [${COMMON_SHA}]"

DATE=$(git show -s --format=%ci ${COMMON_SHA} | cut -d" " -f1)
echo "DATE [${DATE}]"

BRANCH_NAME=slicer-${XYZ}-${DATE}-${COMMON_SHA}
echo "BRANCH_NAME [${BRANCH_NAME}]"

git checkout -b ${BRANCH_NAME}


2. Add slicer remote

git remote add slicer git@github.com:Slicer/SimpleITK

3. Publish branch

git push slicer $BRANCH_NAME