UpdateBot: Nightly -> 4.3

2013-09-05T03:40:54Z

Nightly -> 4.3

New page

<noinclude>{{documentation/versioncheck}}</noinclude>
= Overview =

Extensions can be fully described with an [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|extension description file]] (*.s4ext). This file is automatically generated in the build tree of your extension.

<ol style="list-style-type:none; border-left:thick solid red; padding-left:1em;">
<li>For extension source code associated with git repository, for Slicer revision < [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=22231 r22231], the automatic generation will extract the read/write url.(i.e <code>git@github.com:jcfr/MyExtension.git</code>) whereas the read-only one is expected (i.e <code>git://github.com/jcfr/MyExtension.git</code>). For details see issue [http://www.na-mic.org/Bug/view.php?id=2032 2032] and [http://www.na-mic.org/Bug/view.php?id=2395 2395]</li>
</ol>

To make your extension available for download to Slicer user, this file need to be added to the ExtensionsIndex repository.

You can think of the ExtensionsIndex as a repository containing a list of extension description files (*.s4ext) used by the Slicer extensions build system to build, test, package and upload extensions on an extensions server.

= Prerequisites =
* Extension belongs to Category 1 or Category 2 as described in [[Documentation/{{documentation/version}}/Extensions/CatalogPolicies|Slicer requirements]]
* Extension has been built, tested and installed on at least one platform (Linux, MacOSX or Windows)

= Contributing a new extension =

== Extensions build against Slicer trunk ==

The following instruction describes how to contribute extension description file for an extension being built against slicer trunk.

<ol start="1" style="list-style-type: decimal;">

<li>Fork the <code>ExtensionsIndex</code>: http://github.com/Slicer/ExtensionsIndex. Click [http://help.github.com/forking/ here] for forking instructions.</li>

<li>Clone your fork, then create a topic named <code>add-<ExtensionName></code></li>
<pre>
git clone git@github.com:USER/ExtensionsIndex SlicerExtensionsIndex
cd SlicerExtensionsIndex
git checkout -b add-YourExtensionName
</pre>

<li>Commit your description file. Commit title should be <code>Add YourExtensionName extension</code> and the content should provide details about the extension.</li>
<li>Push the topic to your fork</li>
<pre>
git push origin add-YourExtensionName
</pre>
<li>On your github fork, click on "Pull Request". Slicer folks will be automatically notified.</li>
<li>That's it !</li>

</ol>

* [https://github.com/Slicer/ExtensionsIndex#contributing See instructions on github]
* Consider also reading [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|Extension description file format]]

== Extensions build against Slicer {{Documentation/currentversion}} ==

* Follow instruction reported in section [[Documentation/{{documentation/version}}/Developers/Tutorials/BuildTestPackageDistributeExtensions#Extensions_build_against_Slicer_{{Documentation/currentversion}}_2|Requesting an extension version update / Extensions_build_against_Slicer_{{Documentation/currentversion}}]] and set the title of the commit to be <code>add-<ExtensionName></code>.

= Requesting an extension update =

On your local fork, the idea is to create the following topic branches:
* <code>update-<YourExtensionName></code> based of [https://github.com/Slicer/ExtensionsIndex/tree/master <code>master</code>] integration branch.
* <code>update-<YourExtensionName>-4.2</code> based of [https://github.com/Slicer/ExtensionsIndex/tree/4.2 <code>4.2</code>] integration branch.

== Extensions build against Slicer trunk ==

The following instruction describes how to contribute extension description file updates for an extension being built against slicer trunk.

<ol start="1" style="list-style-type: decimal;">

<li>Update the <code>master</code> branch of both your local clone and your online <code>ExtensionsIndex</code> fork</li>
<pre>
git remote add upstream git://github.com/Slicer/ExtensionsIndex # Add reference to the authoritative ExtensionsIndex
git fetch upstream # Fetch change of the authoritative ExtensionsIndex
git checkout master # Checkout master
git reset --hard upstream/master # Reset your local master branch using the authoritative master
git push origin master # Update the master branch of your online fork
</pre>

<li>If needed, create branch named <code>update-YourExtensionName</code></li>
<pre>
git checkout -B update-YourExtensionName master # Create branch update-YourExtensionName or ensure the existing one starts of updated master
</pre>

<li>Regenerate the <code>YourExtensionName.s4ext</code> file by configuring your extension with CMake</li>
* See https://github.com/Slicer/ExtensionsIndex#build-your-own-set-of-extensions-against-slicer-trunk-build-tree
* If the svn server needs a username and a password, edit the newly generated <code>YourExtensionName.s4ext</code> file to add this information
<li>Commit the <code>YourExtensionName.s4ext</code> file to your cloned ExtensionIndex repository (provide a meaningful commit comment)</li>
<li>Push modifications to your <code>ExtensionIndex</code> fork on github</li>
<pre>
git push origin update-YourExtensionName # Publish the updated branch on your fork
</pre>

<li>Create a pull request:</li>
* Visiting your fork on http://github.com/USER/ExtensionsIndex and, if available, clicking on the <code>Pull request</code> link as explained [https://help.github.com/articles/creating-a-pull-request here].
or
* Using a link similar to the following: <code>https://github.com/USER/ExtensionsIndex/pull/new/update-YourExtensionName</code>

Note: If you are using github for hosting your extension source code, make sure to associated a '''Compare View link'''. This is very helpful to summarize the changes.
<pre>
You can build the compare view URL manually with the following format:

https://github.com/USER/REPO/compare/[USER:]GIT-REF…[USER:]GIT-REF

USER is your GitHub username, REPO is your GitHub repository, and GIT-REF can be a tag, branch, or commit SHA1.
</pre>
Source: http://jbuckley.ca/2011/09/githubs-compare-view/

</ol>

== Extensions build against Slicer {{Documentation/currentversion}} ==

The following instruction describes how to contribute extension description file updates for an extension being built against slicer trunk.

<ol start="1" style="list-style-type: decimal;">

<li>Update the {{Documentation/currentversion}} branch of both your local clone and your online ExtensionsIndex fork</li>
<pre>
git remote add upstream git://github.com/Slicer/ExtensionsIndex # Add reference to the authoritative ExtensionsIndex
git fetch upstream # Fetch change of the authoritative ExtensionsIndex
git checkout 4.2 # Checkout 4.2
git reset --hard upstream/4.2 # Reset your local 4.2 branch using the authoritative 4.2
git push origin 4.2 # Update the 4.2 branch of your online fork
</pre>

<li>If needed, create branch named <code>update-YourExtensionName-4.2</code></li>
<pre>
git checkout -B update-YourExtensionName-4.2 4.2 # Create branch update-YourExtensionName-4.2 or ensure the existing one starts of updated 4.2 branch.
</pre>

<li>Regenerate the <code>YourExtensionName.s4ext</code> file by configuring your extension with CMake</li>
* See https://github.com/Slicer/ExtensionsIndex#build-your-own-set-of-extensions-against-slicer-trunk-build-tree.
* If the svn server needs a username and a password, edit the newly generated <code>YourExtensionName.s4ext</code> file to add this information.
<li>Commit the <code>YourExtensionName.s4ext</code> file to your cloned ExtensionIndex repository providing a meaningful commit comment.</li>
<li>Push modifications to your <code>ExtensionIndex</code> fork on github</li>
<pre>
git push origin update-YourExtensionName-4.2 # Publish the updated branch on your fork
</pre>

<li>Create a pull request:</li>
* Visiting your fork on http://github.com/USER/ExtensionsIndex and, if available, clicking on the <code>Pull request</code> link as explained [https://help.github.com/articles/creating-a-pull-request here].
or
* Using a link similar to the following: <code>https://github.com/USER/ExtensionsIndex/pull/new/update-YourExtensionName-4.2</code>

Note: If you are using github for hosting your extension source code, make sure to associated a '''Compare View link'''. This is very helpful to summarize the changes.
<pre>
You can build the compare view URL manually with the following format:

https://github.com/USER/REPO/compare/[USER:]GIT-REF…[USER:]GIT-REF

USER is your GitHub username, REPO is your GitHub repository, and GIT-REF can be a tag, branch, or commit SHA1.
</pre>
Source: http://jbuckley.ca/2011/09/githubs-compare-view/

</ol>

Documentation/4.3/Developers/Tutorials/Contribute Extension Description File - Revision history

UpdateBot: Nightly -> 4.3