ImageJ

Development
Topics Overview Philosophy Architecture Source code Project management Coding style Debugging
Tools GitHub Git Maven IDEs Travis AppVeyor Dotfiles
Guides Writing plugins ImageJ Ops Contributing to a plugin Distributing your plugins Development lifecycle Building a POM Developing with Eclipse Hands-on debugging Adding new ops Adding new formats Using native libraries Tips for developers Tips for C++ developers ImageJ 1.x plugins Versioning Logging Uber-JARs

If 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

Best practices

Here is a quick summary of the most recommended options:

• Distribution.
  • A) create your own update site; or
  • B) bundle your plugin with Fiji.
• Source code.
  • Make your project open source.
  • Host it on GitHub.
  • Use Maven to build and SemVer for versioning.
  • Use Travis for continuous integration and artifact deployment to the SciJava Maven repository.
• Documentation.
  • Create a page here on the ImageJ Wiki.

The tables below discuss additional 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.

Create your own update site
Steps	Installation	Advantages	Disadvantages
Create your update site, then upload your extension to it. You may add your update site to the list of built-in sites by editing the list of update sites page. To release a new version, upload it to the update site.	Users enable the update site to receive your extension. ImageJ's Updater automatically checks for updates from all enabled update sites.	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.	ImageJ 1.x does not support update sites; users will need to use ImageJ2 (or Fiji: "Fiji Is Just ImageJ2"). You can upgrade an ImageJ 1.x installation to ImageJ2. You will miss out on the tools and tests used to ensure compatibility and reproducibility, making undetected breakages much more likely (at the least).
Distribute it as part of Fiji
Steps	Installation	Advantages	Disadvantages
Make a post on the ImageJ forum to initiate a request.	Users install Fiji, or enable the Fiji update site.	Your extension is available with Fiji out of the box. A Fiji maintainer will help you to manage your project. You can lean on existing tools and documentation to maintain reproducibility of your project. Your project will always be compatible with the latest Fiji distribution. Travis automatically tests your project for errors, deploying successful builds to the SciJava Maven repository.	You must abide by the Fiji contribution requirements. You must rely on a Fiji maintainer (for now) to upload new versions for you.
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.

Host on GitHub in your userspace or organization
Steps	Advantages	Disadvantages
Create an account on GitHub. Create a new repository for your project. Push your code there. Learn Git to manage your code effectively.	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.	Git has a steep learning curve—the GitHub Desktop client makes things easier.
Host on GitHub in the Fiji organization (for extensions distributed with Fiji)
Steps	Advantages	Disadvantages
Request a Fiji maintainer create a repository for you and add you as a contributor. Meet the Fiji contribution requirements.	All the benefits of GitHub. A Fiji maintainer helps 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
Similar to GitHub, but using SourceForge instead.	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 reading the change logs to understand why changes were made. No studying the history to better understand the project's activity. No bisecting the history to track down when bugs were introduced. No safety net to revert unwanted changes or avoid lost work. No branching to maintain multiple development trajectories. No easy switching between versions. No automatic credit and tracking of which authors did which work. No distribution and backup of the project's development history.

Documenting your extension

Useful extensions deserve corresponding documentation explaining how to use them.

Create an ImageJ wiki page
Steps	Advantages	Disadvantages
Create an account. Create a page for your extension.	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 ImageJ Information and Documentation Portal predates the ImageJ wiki, and many extensions are still primarily documented there. The IIDP is a fairly active wiki (but not compared to this one!). The ImageJ developers hope to unify these two wikis in the future.	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
Prepare an HTML page modeled after the list of ImageJ 1.x plugins. Email it to Wayne Rasband, the developer of ImageJ 1.x, and sole maintainer of the ImageJ 1.x website.	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 and VIB Protocol on multiple occasions. And the MBF Plugin Collection went permanently offline!)