Difference between revisions of "Documentation/Nightly/Developers/Tutorials/BuildTestPackageDistributeExtensions"

From Slicer Wiki
Jump to: navigation, search
(moved to readthedocs)
Tags: 2017 source edit, Replaced
 
(95 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 ==
 
* [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 if there is no <code>Pull request</code> link: <code>https://github.com/USER/ExtensionsIndex/pull/new/update-YourExtensionName</code>
 
 
 
<li><p>Submit a pull request to https://github.com/Slicer/ExtensionsIndex providing a meaningful commit comment. If you are using github for hosting your extension source code, Compare View mode is very helpful to summarize the changes. See the instructions how to create a compare view for example [http://jbuckley.ca/2011/09/githubs-compare-view/ here].</p></li>
 
In short (quoting the referenced article):
 
<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>
 
 
 
</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 if there is no <code>Pull request</code> link: <code>https://github.com/USER/ExtensionsIndex/pull/new/update-YourExtensionName-4.2</code>
 
 
 
<li><p>Submit a pull request to https://github.com/Slicer/ExtensionsIndex providing a meaningful commit comment.</p></li>
 
</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>
 
-->
 

Latest revision as of 20:39, 8 June 2020

Home < Documentation < Nightly < Developers < Tutorials < BuildTestPackageDistributeExtensions