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

From Slicer Wiki
Jump to: navigation, search
m
(moved to readthedocs)
Tags: 2017 source edit, Replaced
 
(91 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 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><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-&lt;ExtensionName&gt;</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>
 
-->
 

Latest revision as of 20:39, 8 June 2020

Home < Documentation < Nightly < Developers < Tutorials < BuildTestPackageDistributeExtensions