Documentation/Nightly/Developers/ProjectForks
Contents
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 projectYEAR-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 releaseREV
corresponds to either the first 7 chars of git hash or SVN revision (for exampler1234
)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 ofENH: 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