Difference between revisions of "Documentation/Nightly/Developers/Tutorials/Contribute Extension Description File"

From Slicer Wiki
Jump to: navigation, search
 
(31 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
<noinclude>{{documentation/versioncheck}}</noinclude>
 
= Overview =
 
= 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.
 
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.
  
To make your extension available for download to Slicer user, this file need to be added to a repository named the <code>ExtensionsIndex</code>.
+
<ol style="list-style-type:none; border-left:thick solid red; padding-left:1em;">
 +
  <li><p>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]</p></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.
 
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.
Line 31: Line 36:
 
<li><p>Push the topic to your fork</p></li>
 
<li><p>Push the topic to your fork</p></li>
 
<pre>
 
<pre>
git push origin  
+
git push origin add-YourExtensionName
 
</pre>
 
</pre>
<li><p>On your github fork, click on "Pull Request". Slicer folks will be automatically notified.</p></li>
+
<li>
 +
  <p>On your github fork, click on "Pull Request". [https://help.github.com/articles/creating-a-pull-request Need help ?]</p>
 +
  <ol style="list-style-type:none; border-left:thick solid darkgreen; padding-left:1em;">
 +
    <li><p>Slicer folks will be automatically notified.</p></li>
 +
  </ol>
 +
</li>
 
<li><p>That's it !</p></li>
 
<li><p>That's it !</p></li>
  
 
</ol>
 
</ol>
  
 
 
 
 
* [https://github.com/Slicer/ExtensionsIndex#contributing See instructions on github]
 
 
* Consider also reading [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|Extension description file format]]
 
* Consider also reading [[Documentation/{{documentation/version}}/Developers/Extensions/DescriptionFile|Extension description file format]]
  
 
== Extensions build against Slicer {{Documentation/currentversion}} ==
 
== 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>.
+
* Follow instruction reported in section [[#Extensions_build_against_Slicer_trunk|above]] and select <code>{{documentation/currentversion}}</code> branch when creating the pull request.
  
 
= Requesting an extension update =
 
= Requesting an extension update =
 
+
<!--
On your local fork, the idea is to create the following topic branches:
+
The following tutorials will provide you with detailed instructions to update an extension description files for either the stable Slicer version (<code>{{documentation/currentversion}}</code>) or the Slicer nightly (trunk).
 +
-->
 +
<!--
 +
To summarize, after checking out the ExtensionsIndex, the idea will be 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></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.
+
* <code>update-<YourExtensionName>-{{documentation/currentversion}}</code> based of [https://github.com/Slicer/ExtensionsIndex/tree/{{documentation/currentversion}} <code>{{documentation/currentversion}}</code>] integration branch.
 
+
-->
  
 
== Extensions build against Slicer trunk ==
 
== Extensions build against Slicer trunk ==
Line 73: Line 81:
 
<li><p>If needed, create branch named <code>update-YourExtensionName</code></p></li>
 
<li><p>If needed, create branch named <code>update-YourExtensionName</code></p></li>
 
<pre>
 
<pre>
git checkout -b update-YourExtensionName                         # Create branch update-YourExtensionName
+
git checkout -B update-YourExtensionName master                  # Create branch update-YourExtensionName or ensure the existing one starts of updated master
 
</pre>
 
</pre>
  
<li><p>Regenerate the <code>YourExtensionName.s4ext</code> file by configuring your extension with CMake</p></li>
+
<li>
* See https://github.com/Slicer/ExtensionsIndex#build-your-own-set-of-extensions-against-slicer-trunk-build-tree
+
  <p>Regenerate the <code>YourExtensionName.s4ext</code> file by configuring your extension with CMake</p>
* If the svn server needs a username and a password, edit the newly generated <code>YourExtensionName.s4ext</code> file to add this information
+
  <ol style="list-style-type:none; border-left:thick solid red; padding-left:1em;">
 +
    <li><p> If the svn server needs a username and a password, edit the newly generated <code>YourExtensionName.s4ext</code> file specifying <code>svnusername</code> and <code>svnpassword</code></p></li>
 +
  </ol>
 +
</li>
 
<li><p>Commit the <code>YourExtensionName.s4ext</code> file to your cloned ExtensionIndex repository (provide a meaningful commit comment)</p></li>
 
<li><p>Commit the <code>YourExtensionName.s4ext</code> file to your cloned ExtensionIndex repository (provide a meaningful commit comment)</p></li>
 
<li><p>Push modifications to your <code>ExtensionIndex</code> fork on github</p></li>
 
<li><p>Push modifications to your <code>ExtensionIndex</code> fork on github</p></li>
 
<pre>
 
<pre>
git push origin update-YourExtensionName                         # Publish the updated branch on your fork
+
git push origin update-YourExtensionName --force                  # Publish the updated branch on your fork
 
</pre>
 
</pre>
  
<li><p>Create a pull request:</p></li>
+
<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].
+
  <p>Create a "Pull Request" using a link similar to the following: <code>https://github.com/USER/ExtensionsIndex/pull/new/update-YourExtensionName</code></p>
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.
+
  <ol style="list-style-type:none; border-left:thick solid red; padding-left:1em;">
 +
    <li>
 +
Note: If you are using github for hosting your extension source code, make sure to associated a '''Compare View link''' showing the differences in the source code of your extension (NOT ExtensionIndex!!!) between the previous and current revisions. Compare link is very helpful to summarize the changes.
 
<pre>
 
<pre>
 
You can build the compare view URL manually with the following format:  
 
You can build the compare view URL manually with the following format:  
Line 99: Line 110:
 
</pre>
 
</pre>
 
Source: http://jbuckley.ca/2011/09/githubs-compare-view/
 
Source: http://jbuckley.ca/2011/09/githubs-compare-view/
 +
 +
As a concrete example, in [https://github.com/Slicer/ExtensionsIndex/commit/d8c064ea6f5b182fcf0b1b5c86c03afbd5853de5#diff-d5a6aa1d87d84077acf9eaf33bfcde05 this commit] the version of the LongitudinalPETCT extension was changed from 9b6d4b8 to d033772. The extension repository is located here: https://github.com/paulcm/LongitudinalPETCT/, and therefore the compare link is https://github.com/paulcm/LongitudinalPETCT/compare/9b6d4b8...d033772.
 +
 +
</li></ol>
 +
 +
</li>
  
 
</ol>
 
</ol>
Line 104: Line 121:
 
== Extensions build against Slicer {{Documentation/currentversion}}  ==
 
== 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.
+
The following instruction describes how to contribute extension description file updates for an extension being built against slicer {{documentation/currentversion}}.
  
 
<ol start="1" style="list-style-type: decimal;">
 
<ol start="1" style="list-style-type: decimal;">
Line 112: Line 129:
 
git remote add upstream git://github.com/Slicer/ExtensionsIndex  # Add reference to the authoritative ExtensionsIndex
 
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 fetch upstream                                                # Fetch change of the authoritative ExtensionsIndex
git checkout 4.2                                                 # Checkout 4.2
+
git checkout 4.3                                                 # Checkout 4.3
git reset --hard upstream/4.2                                     # Reset your local 4.2 branch using the authoritative 4.2
+
git reset --hard upstream/4.3                                     # Reset your local 4.3 branch using the authoritative 4.3
git push origin 4.2                                               # Update the 4.2 branch of your online fork
+
git push origin 4.3                                               # Update the 4.3 branch of your online fork
 
</pre>
 
</pre>
  
<li><p>If needed, create branch named <code>update-YourExtensionName-4.2</code></p></li>
+
<li><p>If needed, create branch named <code>update-YourExtensionName-{{Documentation/currentversion}}</code></p></li>
 
<pre>
 
<pre>
git checkout -b update-YourExtensionName-4.2                      # Create branch update-YourExtensionName-4.2
+
git checkout -B update-YourExtensionName-4.3 4.3                  # Create branch update-YourExtensionName-4.3 or ensure the existing one starts of updated 4.3 branch.
 
</pre>
 
</pre>
  
Line 129: Line 146:
 
<li><p>Push modifications to your <code>ExtensionIndex</code> fork on github</p></li>
 
<li><p>Push modifications to your <code>ExtensionIndex</code> fork on github</p></li>
 
<pre>
 
<pre>
git push origin update-YourExtensionName-4.2                    # Publish the updated branch on your fork
+
git push origin update-YourExtensionName-4.3  --force            # Publish the updated branch on your fork
 
</pre>
 
</pre>
  
<li><p>Create a pull request:</p></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.
+
<li>
 +
  <p>Create a "Pull Request" using a link similar to the following: <code>https://github.com/USER/ExtensionsIndex/pull/new/update-YourExtensionName-{{Documentation/currentversion}}</code></p>
 +
 
 +
  <ol style="list-style-type:none; border-left:thick solid red; padding-left:1em;">
 +
    <li>
 +
Note: If you are using github for hosting your extension source code, make sure to associated a '''Compare View link''' showing the differences in the source code of your extension (NOT ExtensionIndex!!!) between the previous and current revisions. Compare link is very helpful to summarize the changes.
 
<pre>
 
<pre>
 
You can build the compare view URL manually with the following format:  
 
You can build the compare view URL manually with the following format:  
Line 147: Line 165:
 
Source: http://jbuckley.ca/2011/09/githubs-compare-view/
 
Source: http://jbuckley.ca/2011/09/githubs-compare-view/
  
</ol>
+
As a concrete example, in [https://github.com/Slicer/ExtensionsIndex/commit/d8c064ea6f5b182fcf0b1b5c86c03afbd5853de5#diff-d5a6aa1d87d84077acf9eaf33bfcde05 this commit] the version of the LongitudinalPETCT extension was changed from 9b6d4b8 to d033772. The extension repository is located here: https://github.com/paulcm/LongitudinalPETCT/, and therefore the compare link is https://github.com/paulcm/LongitudinalPETCT/compare/9b6d4b8...d033772.
 +
 
 +
</li></ol>
 +
 
 +
</li>
 +
 
  
 
<!--
 
<!--

Latest revision as of 18:54, 9 December 2014

Home < Documentation < Nightly < Developers < Tutorials < Contribute Extension Description File


For the latest Slicer documentation, visit the read-the-docs.


Overview

Extensions can be fully described with an extension description file (*.s4ext). This file is automatically generated in the build tree of your extension.

  1. For extension source code associated with git repository, for Slicer revision < r22231, the automatic generation will extract the read/write url.(i.e git@github.com:jcfr/MyExtension.git) whereas the read-only one is expected (i.e git://github.com/jcfr/MyExtension.git). For details see issue 2032 and 2395

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

  1. Fork the ExtensionsIndex: http://github.com/Slicer/ExtensionsIndex. Click here for forking instructions.

  2. Clone your fork, then create a topic named add-<ExtensionName>

  3. git clone git@github.com:USER/ExtensionsIndex SlicerExtensionsIndex
    cd SlicerExtensionsIndex
    git checkout -b add-YourExtensionName
    
  4. Commit your description file. Commit title should be Add YourExtensionName extension and the content should provide details about the extension.

  5. Push the topic to your fork

  6. git push origin add-YourExtensionName
    
  7. On your github fork, click on "Pull Request". Need help ?

    1. Slicer folks will be automatically notified.

  8. That's it !

Extensions build against Slicer 4.10

  • Follow instruction reported in section above and select 4.10 branch when creating the pull request.

Requesting an extension update

Extensions build against Slicer trunk

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

  1. Update the master branch of both your local clone and your online ExtensionsIndex fork

  2. 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
    
  3. If needed, create branch named update-YourExtensionName

  4. git checkout -B update-YourExtensionName master                   # Create branch update-YourExtensionName or ensure the existing one starts of updated master
    
  5. Regenerate the YourExtensionName.s4ext file by configuring your extension with CMake

    1. If the svn server needs a username and a password, edit the newly generated YourExtensionName.s4ext file specifying svnusername and svnpassword

  6. Commit the YourExtensionName.s4ext file to your cloned ExtensionIndex repository (provide a meaningful commit comment)

  7. Push modifications to your ExtensionIndex fork on github

  8. git push origin update-YourExtensionName --force                  # Publish the updated branch on your fork
    
  9. Create a "Pull Request" using a link similar to the following: https://github.com/USER/ExtensionsIndex/pull/new/update-YourExtensionName

    1. Note: If you are using github for hosting your extension source code, make sure to associated a Compare View link showing the differences in the source code of your extension (NOT ExtensionIndex!!!) between the previous and current revisions. Compare link is very helpful to summarize the changes.
      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. 
      

      Source: http://jbuckley.ca/2011/09/githubs-compare-view/

      As a concrete example, in this commit the version of the LongitudinalPETCT extension was changed from 9b6d4b8 to d033772. The extension repository is located here: https://github.com/paulcm/LongitudinalPETCT/, and therefore the compare link is https://github.com/paulcm/LongitudinalPETCT/compare/9b6d4b8...d033772.

Extensions build against Slicer 4.10

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

  1. Update the 4.10 branch of both your local clone and your online ExtensionsIndex fork

  2. 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.3                                                  # Checkout 4.3
    git reset --hard upstream/4.3                                     # Reset your local 4.3 branch using the authoritative 4.3
    git push origin 4.3                                               # Update the 4.3 branch of your online fork
    
  3. If needed, create branch named update-YourExtensionName-4.10

  4. git checkout -B update-YourExtensionName-4.3 4.3                  # Create branch update-YourExtensionName-4.3 or ensure the existing one starts of updated 4.3 branch.
    


  5. Regenerate the YourExtensionName.s4ext file by configuring your extension with CMake

  6. Commit the YourExtensionName.s4ext file to your cloned ExtensionIndex repository providing a meaningful commit comment.

  7. Push modifications to your ExtensionIndex fork on github

  8. git push origin update-YourExtensionName-4.3  --force             # Publish the updated branch on your fork
    


  9. Create a "Pull Request" using a link similar to the following: https://github.com/USER/ExtensionsIndex/pull/new/update-YourExtensionName-4.10

    1. Note: If you are using github for hosting your extension source code, make sure to associated a Compare View link showing the differences in the source code of your extension (NOT ExtensionIndex!!!) between the previous and current revisions. Compare link is very helpful to summarize the changes.
      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. 
      

      Source: http://jbuckley.ca/2011/09/githubs-compare-view/

      As a concrete example, in this commit the version of the LongitudinalPETCT extension was changed from 9b6d4b8 to d033772. The extension repository is located here: https://github.com/paulcm/LongitudinalPETCT/, and therefore the compare link is https://github.com/paulcm/LongitudinalPETCT/compare/9b6d4b8...d033772.