Difference between revisions of "Documentation/Nightly/Developers/Tutorials/Contribute Extension Description File"
m |
|||
Line 38: | Line 38: | ||
git push origin add-YourExtensionName | git push origin add-YourExtensionName | ||
</pre> | </pre> | ||
− | <li><p>On your github fork, click on "Pull Request" | + | <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> | ||
Revision as of 16:34, 6 November 2013
Home < Documentation < Nightly < Developers < Tutorials < Contribute Extension Description File
For the latest Slicer documentation, visit the read-the-docs. |
Contents
Overview
Extensions can be fully described with an extension description file (*.s4ext). This file is automatically generated in the build tree of your extension.
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.egit://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.
Fork the
ExtensionsIndex
: http://github.com/Slicer/ExtensionsIndex. Click here for forking instructions.Clone your fork, then create a topic named
add-<ExtensionName>
Commit your description file. Commit title should be
Add YourExtensionName extension
and the content should provide details about the extension.Push the topic to your fork
-
On your github fork, click on "Pull Request". Need help ?
Slicer folks will be automatically notified.
That's it !
git clone git@github.com:USER/ExtensionsIndex SlicerExtensionsIndex cd SlicerExtensionsIndex git checkout -b add-YourExtensionName
git push origin add-YourExtensionName
- Consider also reading Extension description file format
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.
Update the
master
branch of both your local clone and your onlineExtensionsIndex
forkIf needed, create branch named
update-YourExtensionName
-
Regenerate the
YourExtensionName.s4ext
file by configuring your extension with CMakeIf the svn server needs a username and a password, edit the newly generated
YourExtensionName.s4ext
file specifyingsvnusername
andsvnpassword
Commit the
YourExtensionName.s4ext
file to your cloned ExtensionIndex repository (provide a meaningful commit comment)Push modifications to your
ExtensionIndex
fork on githubCreate a pull request:
- Visiting your fork on http://github.com/USER/ExtensionsIndex and, if available, clicking on the
Pull request
link as explained here. - Using a link similar to the following:
https://github.com/USER/ExtensionsIndex/pull/new/update-YourExtensionName
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
git checkout -B update-YourExtensionName master # Create branch update-YourExtensionName or ensure the existing one starts of updated master
git push origin update-YourExtensionName # Publish the updated branch on your fork
or
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.
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.
Update the 4.10 branch of both your local clone and your online ExtensionsIndex fork
If needed, create branch named
update-YourExtensionName-4.3
Regenerate the
YourExtensionName.s4ext
file by configuring your extension with CMake- 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
YourExtensionName.s4ext
file to add this information. Commit the
YourExtensionName.s4ext
file to your cloned ExtensionIndex repository providing a meaningful commit comment.Push modifications to your
ExtensionIndex
fork on githubCreate a pull request:
- Visiting your fork on http://github.com/USER/ExtensionsIndex and, if available, clicking on the
Pull request
link as explained here. - Using a link similar to the following:
https://github.com/USER/ExtensionsIndex/pull/new/update-YourExtensionName-4.3
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
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.
git push origin update-YourExtensionName-4.3 # Publish the updated branch on your fork
or
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.
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.