|
Tags: 2017 source edit, Replaced |
| (92 intermediate revisions by 6 users not shown) |
| Line 1: |
Line 1: |
| − | = Prerequisites =
| + | <noinclude>{{documentation/versioncheck}}</noinclude> |
| | | | |
| − | == Obtain an API key to submit on the extension server ==
| + | {{documentation/banner |
| − | | + | | text = [https://slicer.readthedocs.io/en/latest/developer_guide/extensions.html This page has been moved to read-the-docs.] |
| − | {{:Documentation/{{documentation/version}}/Developers/Tutorials/ObtainExtensionServerApiKey}}
| + | | background-color = 8FBC8F }} |
| − | | |
| − | ==Upload an extension in the experimental folder==
| |
| − | [https://github.com/Slicer/ExtensionsIndex#manual-build See instructions on github]
| |
| − | | |
| − | | |
| − | = Extensions index =
| |
| − | | |
| − | {{:Documentation/{{documentation/version}}/Developers/Extensions/Index}}
| |
| − | | |
| − | | |
| − | = Contributing an extension =
| |
| − | | |
| − | There are multiple branches on the ExtensionsIndex:
| |
| − | | |
| − | * <code>master</code>: This branch contain description files of extensions that will be built against Slicer nightly.
| |
| − | * [...]
| |
| − | * <code>{{documentation/currentversion}}</code>: This branch contain description files of extensions that will be built against latest Slicer {{documentation/currentversion}} available patch release.
| |
| − | | |
| − | The reasoning behind this conservative approach is that since both the Slicer API and ABI associated with Slicer base libraries are changing often, extensions available for download for a given revision of Slicer are built against that same revision of Slicer.
| |
| − | | |
| − | It means that developer willing to have their extensions available on the different versions of Slicer will have to submit [[#Submitting_a_pull_request|pull requests]] for each version.
| |
| − | | |
| − | == 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><p>Fork the <code>ExtensionsIndex</code>: http://github.com/Slicer/ExtensionsIndex. Click [http://help.github.com/forking/ here] for forking instructions.</p></li>
| |
| − | | |
| − | <li><p>Clone your fork, then create a topic named <code>add-<ExtensionName></code></p></li>
| |
| − | <pre>
| |
| − | git clone git@github.com:USER/ExtensionsIndex SlicerExtensionsIndex
| |
| − | cd SlicerExtensionsIndex
| |
| − | git checkout -b add-YourExtensionName
| |
| − | </pre>
| |
| − | | |
| − | <li><p>Commit your description file. Commit title should be <code>Add YourExtensionName extension</code> and the content should provide details about the extension.</p></li>
| |
| − | <li><p>Push the topic to your fork</p></li>
| |
| − | <pre>
| |
| − | git push origin
| |
| − | </pre>
| |
| − | <li><p>On your github fork, click on "Pull Request". Slicer folks will be automatically notified.</p></li>
| |
| − | <li><p>That's it !</p></li>
| |
| − | | |
| − | </ol>
| |
| − | | |
| − | | |
| − | | |
| − | | |
| − | | |
| − | * [https://github.com/Slicer/ExtensionsIndex#contributing See instructions on github]
| |
| − | * Consider also reading [https://github.com/Slicer/ExtensionsIndex/wiki/Extension-description-file 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><p>Update the <code>master</code> branch of both your local clone and your online <code>ExtensionsIndex</code> fork</p></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><p>If needed, create branch named <code>update-YourExtensionName</code></p></li>
| |
| − | <pre>
| |
| − | git checkout -b update-YourExtensionName # Create branch update-YourExtensionName
| |
| − | </pre>
| |
| − | | |
| − | <li><p>Regenerate the <code>YourExtensionName.s4ext</code> file by configuring your extension with CMake</p></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><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>
| |
| − | <pre>
| |
| − | git push origin update-YourExtensionName # Publish the updated branch on your fork
| |
| − | </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</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><p>Update the {{Documentation/currentversion}} branch of both your local clone and your online ExtensionsIndex fork</p></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><p>If needed, create branch named <code>update-YourExtensionName-4.2</code></p></li>
| |
| − | <pre>
| |
| − | git checkout -b update-YourExtensionName-4.2 # Create branch update-YourExtensionName-4.2
| |
| − | </pre>
| |
| − | | |
| − | | |
| − | <li><p>Regenerate the <code>YourExtensionName.s4ext</code> file by configuring your extension with CMake</p></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><p>Commit the <code>YourExtensionName.s4ext</code> file to your cloned ExtensionIndex repository providing a meaningful commit comment.</p></li>
| |
| − | <li><p>Push modifications to your <code>ExtensionIndex</code> fork on github</p></li>
| |
| − | <pre>
| |
| − | git push origin update-YourExtensionName-4.2 # Publish the updated branch on your fork
| |
| − | </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.
| |
| − | <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>
| |
| − | | |
| − | <!--
| |
| − | = Submitting a pull request =
| |
| − | | |
| − | The following gallery illustrates how to submit a pull request from your <code>ExtensionsIndex</code> fork.
| |
| − | | |
| − | To learn more about pull request. Consider reading: https://help.github.com/articles/using-pull-requests
| |
| − | | |
| − | <gallery widths=800px heights=300px perrow=1>
| |
| − | File:Extensions-4.2-pull-request-step1.png|1. Create Pull Request
| |
| − | File:Extensions-4.2-pull-request-step2.png|2. Select base
| |
| − | File:Extensions-4.2-pull-request-step3.png|3. Send Pull Request
| |
| − | File:Extensions-4.2-pull-request-step4.png|4. Verify
| |
| − | </gallery>
| |
| − | -->
| |
