Documentation/Nightly/Developers/ProjectForks - Revision history

JChris.FillionR: /* FAQ */

2018-03-08T16:08:23Z

FAQ

JChris.FillionR at 16:08, 8 March 2018

2018-03-08T16:08:05Z

JChris.FillionR: /* Caveats */

2017-10-27T17:13:08Z

Caveats

JChris.FillionR: JChris.FillionR moved page Documentation/Nightly/Developers/Tutorials/ProjectForks to Documentation/Nightly/Developers/ProjectForks

2017-10-23T20:06:05Z

JChris.FillionR moved page Documentation/Nightly/Developers/Tutorials/ProjectForks to Documentation/Nightly/Developers/ProjectForks

JChris.FillionR: Created page with " == 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 fo..."

2017-10-23T20:05:03Z

Created page with " == 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 fo..."

New page

== 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: <code>slicer-vX.Y.Z-YEAR-MONTH-DAY</code> where
* <code>X.Y.Z</code> corresponds to the version of the fork project
* <code>YEAR-MONTH-DAY</code> corresponds to the date of the last official commit of the fork project.

For example, in case of the [https://github.com/Slicer/VTK Slicer/VTK] fork, the branch <code>slicer-v6.2.0-2015-03-02</code> 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: <code>slicer-vX.Y-YEAR-MONTH-DAY-REV</code> where

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

For example: <code>slicer-v6.2.0-2015-02-24-70bad0e</code>

== 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:

<pre>
git shortlog sha_before..sha_after --no-merges
</pre>

where <code>sha_before</code> and <code>sha_after</code> are the first seven charachers of the SHA.

Here is an example of commit updating <code>External_VTKv6.cmake</code> in Slicer:

<pre>
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.
</pre>

Source: [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=25160 r25160]

=== Caveats ===

* For the commit title, prefer something like <code>ENH: Update VTK to ...</code> instead of <code>ENH: Update VTK git tag to ...</code>

* If there is only commit in the update, it is reasonable to copy the message. For example, see [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=24693 r24693].

* If the copied message reference the sha1 of its project (e.g VTK), change it to this form <code>org/proj@sha</code>. For example, see [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=24693 r24693].

* 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]

@@ Line 71: / Line 71: @@
 == FAQ ==
-=== How to create the slicer- branch from a topic being contributed upstream ?  ===
+=== 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.

← Older revision		Revision as of 16:08, 8 March 2018
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

@@ Line 63: / Line 63: @@
 * For the commit title, prefer something like <code>ENH: Update VTK to ...</code> instead of <code>ENH: Update VTK git tag to ...</code>
-* If there is only commit in the update, it is reasonable to copy the message. For example, see [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=24693 r24693].
+* If there is only one commit in the update, it is reasonable to copy the message. For example, see [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=24693 r24693].
 * If the copied message reference the sha1 of its project (e.g VTK), change it to this form <code>org/proj@sha</code>. For example, see [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=24693 r24693].
 * 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]

← Older revision	Revision as of 20:06, 23 October 2017
(No difference)