Difference between revisions of "Distribution"

(Sharing your source code: Split up SourceForge cons into bullets)
(Improve table formatting)
Line 9: Line 9:
  
 
The first goal is to get your extension into the hands of users.
 
The first goal is to get your extension into the hands of users.
{{Tip|tip = The best way to distribute your extension is to '''[[How to set up and populate an update site|create an update site]]'''!}}{| class="wikitable"
+
{{Tip|tip = The best way to distribute your extension is to '''[[How to set up and populate an update site|create an update site]]'''!}}{| class="wikitable" style="border: none"
 
| colspan="4" style="background: #afa" | '''Create your own update site'''
 
| colspan="4" style="background: #afa" | '''Create your own update site'''
 
|-
 
|-
Line 32: Line 32:
 
| style="background: #dfd; vertical-align: top" |
 
| style="background: #dfd; vertical-align: top" |
 
* '''[[ImageJ 1.x]]''' does not support update sites; users will need to use '''[[ImageJ2]]''' (or '''[[Fiji]]''': "Fiji Is Just ImageJ2"). You can '''[[Updater#Bootstrapping_the_updater|convert an ImageJ 1.x installation to ImageJ2]]'''.
 
* '''[[ImageJ 1.x]]''' does not support update sites; users will need to use '''[[ImageJ2]]''' (or '''[[Fiji]]''': "Fiji Is Just ImageJ2"). You can '''[[Updater#Bootstrapping_the_updater|convert an ImageJ 1.x installation to ImageJ2]]'''.
|}
+
|-
{| class="wikitable"
+
| colspan="4" style="background: white; border: none; height: 1em" |
 +
|-
 
| colspan="4" style="background: lightgray" | '''Distribute it as part of Fiji'''
 
| colspan="4" style="background: lightgray" | '''Distribute it as part of Fiji'''
 
|-
 
|-
Line 51: Line 52:
 
* You must abide by the [[Fiji contribution requirements]].
 
* You must abide by the [[Fiji contribution requirements]].
 
* You must rely on a Fiji administrator to upload new versions for you.
 
* You must rely on a Fiji administrator to upload new versions for you.
 +
|-
 +
| colspan="4" style="background: white; border: none; height: 1em" |
 
|-
 
|-
 
| colspan="4" style="background: lightgray" | '''Serve it from a website as a download'''
 
| colspan="4" style="background: lightgray" | '''Serve it from a website as a download'''
Line 77: Line 80:
  
 
If you want to facilitate good science, please [[Open Source|share your source code]]. Otherwise, your extension is a black box and its results are not verifiable.
 
If you want to facilitate good science, please [[Open Source|share your source code]]. Otherwise, your extension is a black box and its results are not verifiable.
{{Tip|tip=The recommended way to share your source is to host it on '''[https://github.com/ GitHub]'''!}}{| class="wikitable"
+
{{Tip|tip=The recommended way to share your source is to host it on '''[https://github.com/ GitHub]'''!}}{| class="wikitable" style="border: none"
 
| colspan="3" style="background: #afa" | '''Host on GitHub in your userspace or organization'''
 
| colspan="3" style="background: #afa" | '''Host on GitHub in your userspace or organization'''
 
|-
 
|-
Line 97: Line 100:
 
| style="background: #dfd; vertical-align: top" |
 
| style="background: #dfd; vertical-align: top" |
 
* Git has a steep learning curve—the '''[https://windows.github.com/ GitHub for Windows]''' and '''[https://mac.github.com/ GitHub for Mac]''' clients make things easier.
 
* Git has a steep learning curve—the '''[https://windows.github.com/ GitHub for Windows]''' and '''[https://mac.github.com/ GitHub for Mac]''' clients make things easier.
|}
+
|-
{| class="wikitable"
+
| colspan="3" style="background: white; border: none; height: 1em" |
 +
|-
 
| colspan="3" style="background: lightgray" | '''Host on GitHub in the Fiji organization'''
 
| colspan="3" style="background: lightgray" | '''Host on GitHub in the Fiji organization'''
 
|-
 
|-
Line 113: Line 117:
 
| style="vertical-align: top" |
 
| style="vertical-align: top" |
 
* You must abide by the Fiji contribution requirements.
 
* You must abide by the Fiji contribution requirements.
 +
|-
 +
| colspan="3" style="background: white; border: none; height: 1em" |
 
|-
 
|-
 
| colspan="3" style="background: lightgray" | '''Host on BitBucket'''
 
| colspan="3" style="background: lightgray" | '''Host on BitBucket'''
Line 127: Line 133:
 
* ImageJ and related projects are hosted on GitHub, not BitBucket.
 
* ImageJ and related projects are hosted on GitHub, not BitBucket.
 
* BitBucket has a smaller user base than GitHub does.
 
* BitBucket has a smaller user base than GitHub does.
 +
|-
 +
| colspan="3" style="background: white; border: none; height: 1em" |
 
|-
 
|-
 
| colspan="3" style="background: lightgray" | '''Host on SourceForge'''
 
| colspan="3" style="background: lightgray" | '''Host on SourceForge'''
Line 146: Line 154:
 
* SourceForge has a lot of downtime. (The [http://jenkins.imagej.net/view/Mirrors/ ImageJ mirrors of SourceForge projects] hence have a lot of problems.)
 
* SourceForge has a lot of downtime. (The [http://jenkins.imagej.net/view/Mirrors/ ImageJ mirrors of SourceForge projects] hence have a lot of problems.)
 
* Using SourceForge is highly discouraged compared to other code hosting sites.
 
* Using SourceForge is highly discouraged compared to other code hosting sites.
 +
|-
 +
| colspan="3" style="background: white; border: none; height: 1em" |
 
|-
 
|-
 
| colspan="3" style="background: lightgray" | '''Serve it from a website as a download'''
 
| colspan="3" style="background: lightgray" | '''Serve it from a website as a download'''
Line 171: Line 181:
  
 
Useful extensions deserve corresponding documentation explaining how to use them.
 
Useful extensions deserve corresponding documentation explaining how to use them.
{{Tip|tip=The best place to document your extension is here on the '''[http://imagej.net/ ImageJ Wiki]'''!}}{| class="wikitable"
+
{{Tip|tip=The best place to document your extension is here on the '''[http://imagej.net/ ImageJ Wiki]'''!}}{| class="wikitable" style="border: none"
 
| colspan="3" style="background: #afa" | '''Create an ImageJ wiki page'''
 
| colspan="3" style="background: #afa" | '''Create an ImageJ wiki page'''
 
|-
 
|-
Line 187: Line 197:
 
| style="background: #dfd; vertical-align: top" |
 
| style="background: #dfd; vertical-align: top" |
 
-
 
-
|}
+
|-
{| class="wikitable"
+
| colspan="3" style="background: white; border: none; height: 1em" |
 +
|-
 
| colspan="3" style="background: lightgray" | '''Use the ImageJ Information and Documentation Portal (IIDP)'''
 
| colspan="3" style="background: lightgray" | '''Use the ImageJ Information and Documentation Portal (IIDP)'''
 
|-
 
|-
Line 206: Line 217:
 
* You must explicitly request an IIDP account from an administrator.
 
* You must explicitly request an IIDP account from an administrator.
 
* The wiki uses Plone, a lesser known CMS engine.
 
* The wiki uses Plone, a lesser known CMS engine.
 +
|-
 +
| colspan="3" style="background: white; border: none; height: 1em" |
 
|-
 
|-
 
| colspan="3" style="background: lightgray" | '''Add a page to the ImageJ 1.x website'''
 
| colspan="3" style="background: lightgray" | '''Add a page to the ImageJ 1.x website'''
Line 222: Line 235:
 
* Hence, turnaround time on updates is longer.
 
* Hence, turnaround time on updates is longer.
 
* The list of plugins there is extensive and difficult to sort through.
 
* The list of plugins there is extensive and difficult to sort through.
 +
|-
 +
| colspan="3" style="background: white; border: none; height: 1em" |
 
|-
 
|-
 
| colspan="3" style="background: lightgray" | '''Create your own webpage elsewhere'''
 
| colspan="3" style="background: lightgray" | '''Create your own webpage elsewhere'''

Revision as of 13:36, 13 November 2014

Template:DevelopmentIf you create a useful extension of ImageJ—e.g., a plugin, script or macro—the next step is to distribute it to others, including:

  • Distribute the extension itself to users
  • Share the extension's source code
  • Document the extension somewhere

The tables below discuss options for these three aspects of distribution. Green items are recommended. Other options are given but not recommended for various reasons.

Distributing your extension

The first goal is to get your extension into the hands of users.

Tip: The best way to distribute your extension is to create an update site!
Create your own update site
Steps Installation Advantages Disadvantages
  • You do not need server space to host your extensions; you can use a personal update site hosted on the ImageJ web site.
  • Alternately, you can retain full control by hosting your update site yourself.
  • Users are notified of updates without needing to check proactively.
  • The updater manages dependencies for you.
  • You can automate distribution using the command line updater.
Distribute it as part of Fiji
Steps Installation Advantages Disadvantages
  • Your extension is available with Fiji out of the box.
  • A Fiji administrator will help (force ;-) you to manage your project.
Serve it from a website as a download
Steps Installation Advantages Disadvantages
  • Create an archive (TAR, ZIP, etc.).
  • Upload the archive to the relevant web space, and link it.
  • Users download the archive, unpacking it into ImageJ's plugins folder.
  • You avoid the activation barrier of learning to use the Updater.
  • ImageJ2 is not required to install the extension.
  • Users must find your plugin via a link or web search.
  • Users must perform a manual installation procedure.
  • Users must manually check for later updates.
  • Users will report bugs found in outdated versions of the extension.

Sharing your source code

If you want to facilitate good science, please share your source code. Otherwise, your extension is a black box and its results are not verifiable.

Tip: The recommended way to share your source is to host it on GitHub!
Host on GitHub in your userspace or organization
Steps Advantages Disadvantages
  • Git is an incredibly powerful way to keep track of your code.
  • GitHub greatly facilitates collaboration: sharing ideas and patches.
  • Seriously: Git and GitHub are amazing tools, and you will be orders of magnitude less effective without them.
  • "Doing it in public" is a great way to stop sucking and be awesome instead.
  • All of ImageJ, Fiji and related SciJava projects are hosted on GitHub.
Host on GitHub in the Fiji organization
Steps Advantages Disadvantages
  • All the benefits of GitHub.
  • A Fiji maintainer helps (forces ;-) you to manage your project.
  • You must abide by the Fiji contribution requirements.
Host on BitBucket
Steps Advantages Disadvantages
  • Similar to GitHub, but using BitBucket instead.
  • Similar to GitHub.
  • ImageJ and related projects are hosted on GitHub, not BitBucket.
  • BitBucket has a smaller user base than GitHub does.
Host on SourceForge
Steps Advantages Disadvantages
  • SourceForge predates GitHub; some people prefer it.
  • The interface is not as powerful as GitHub and BitBucket:
    • Common workflows require many more mouse clicks.
    • The user interfaces of GitHub and BitBucket provide much better guidance.
    • SourceForge's servers tend to be very slow compared to GitHub and BitBucket.
    • The collaboration features are vastly inferior.
  • SourceForge has a lot of downtime. (The ImageJ mirrors of SourceForge projects hence have a lot of problems.)
  • Using SourceForge is highly discouraged compared to other code hosting sites.
Serve it from a website as a download
Steps Advantages Disadvantages
  • Create an archive (TAR, ZIP, etc.).
  • Upload the archive to the relevant web space, and link it.
  • Users download and unpack the archive.
  • You avoid the activation barrier of learning a revision control system.
  • No revision control system.
  • No easy browsing of source code online.
  • No easy submission of patches.
  • No finding the code in web searches.
  • No revision control system.
  • No revision control system!

Documenting your extension

Useful extensions deserve corresponding documentation explaining how to use them.

Tip: The best place to document your extension is here on the ImageJ Wiki!
Create an ImageJ wiki page
Steps Advantages Disadvantages
  • The ImageJ wiki is part of imagej.net, the integrated ImageJ web site.
  • The ImageJ wiki uses MediaWiki, the most popular wiki engine which drives Wikipedia.
  • You can get started immediately; no human needs to approve your account or edits.

-

Use the ImageJ Information and Documentation Portal (IIDP)
Steps Advantages Disadvantages
  • Request an account from an IIDP administrator.
  • Create a page for your extension.
  • The IIDP documents only ImageJ 1.x, not ImageJ2.
  • You must explicitly request an IIDP account from an administrator.
  • The wiki uses Plone, a lesser known CMS engine.
Add a page to the ImageJ 1.x website
Steps Advantages Disadvantages
  • Listed on the ImageJ 1.x website.
  • Not collaborative. No one else can edit the ImageJ 1.x website—not even you!
  • Hence, turnaround time on updates is longer.
  • The list of plugins there is extensive and difficult to sort through.
Create your own webpage elsewhere
Steps Advantages Disadvantages
(Varies)
  • Total control of the content
  • Nonstandard location. Users may have trouble finding your documentation.
  • Not collaborative. No one else can improve the documentation.
  • If your site goes down, users lose access to the information. (This happened with the 3D Viewer a while back. And the MBF Plugin Collection went permanently offline!)