Difference between revisions of "Distribution"
(→Distributing your extension) |
(Fix typo) |
||
(28 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
− | {{ | + | __NOTOC__{{DevelopMenu | tutorials}}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 | * '''Distribute''' the extension itself to users | ||
* Share the extension's '''source code''' | * Share the extension's '''source code''' | ||
* '''Document''' the extension somewhere | * '''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. | + | == Best practices == |
+ | |||
+ | Here is a quick summary of the most recommended options: | ||
+ | * '''Distribution.''' | ||
+ | ** A) '''[[How to set up and populate an update site|create your own update site]]'''; or | ||
+ | ** B) '''[[Fiji contribution requirements|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 '''[http://imagej.net/ 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 == | == Distributing your extension == | ||
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. | ||
− | + | {| 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 19: | Line 33: | ||
| style="background: #dfd; vertical-align: top" | | | style="background: #dfd; vertical-align: top" | | ||
* '''[[How to set up and populate an update site| Create your update site]]''', then '''[[How to set up and populate an update site#Uploading_files_to_your_update_site|upload your extension to it]]'''. | * '''[[How to set up and populate an update site| Create your update site]]''', then '''[[How to set up and populate an update site#Uploading_files_to_your_update_site|upload your extension to it]]'''. | ||
− | * You may add your update site to the list of built-in sites by editing the ''' | + | * You may add your update site to the list of built-in sites by editing the '''{{ListOfUpdateSites}}''' page. |
* To release a new version, '''[[How to set up and populate an update site#Uploading_files_to_your_update_site|upload it to the update site]]'''. | * To release a new version, '''[[How to set up and populate an update site#Uploading_files_to_your_update_site|upload it to the update site]]'''. | ||
| style="background: #dfd; vertical-align: top" | | | style="background: #dfd; vertical-align: top" | | ||
Line 31: | Line 45: | ||
* You can automate distribution using the '''[[Updater#Command-line_usage|command line updater]]'''. | * You can automate distribution using the '''[[Updater#Command-line_usage|command line updater]]'''. | ||
| 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| | + | * '''[[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|upgrade an ImageJ 1.x installation to ImageJ2]]'''. |
− | | | + | * You will miss out on the '''[[Project_management|tools and tests]]''' used to ensure compatibility and reproducibility, making undetected breakages much more likely (at the least). |
− | + | |- | |
− | | colspan="4" style="background: | + | | colspan="4" style="background: white; border: none; height: 1em" | |
+ | |- | ||
+ | | colspan="4" style="background: #afa" | '''Distribute it as part of Fiji''' | ||
|- | |- | ||
− | |'''Steps''' | + | | style="background: #dfd" |'''Steps''' |
− | |'''Installation''' | + | | style="background: #dfd" |'''Installation''' |
− | |'''Advantages''' | + | | style="background: #dfd" |'''Advantages''' |
− | |'''Disadvantages''' | + | | style="background: #dfd" |'''Disadvantages''' |
|- | |- | ||
− | | style="vertical-align: top" | | + | | style="background: #dfd; vertical-align: top" | |
− | * | + | * Make a post on the '''[[Forum|ImageJ forum]]''' to initiate a request. |
− | | style="vertical-align: top" | | + | | style="background: #dfd; vertical-align: top" | |
− | * Users [[Downloads|install Fiji]], or [[How to follow a 3rd party update site|enable the Fiji update site]]. | + | * Users '''[[Fiji/Downloads|install Fiji]]''', or '''[[How to follow a 3rd party update site|enable the Fiji update site]]'''. |
− | | style="vertical-align: top" | | + | | style="background: #dfd; vertical-align: top" | |
* Your extension is available with Fiji out of the box. | * Your extension is available with Fiji out of the box. | ||
− | * A Fiji | + | * A '''[[Governance|Fiji maintainer]]''' will help you to manage your project. |
− | | style="vertical-align: top" | | + | * You can lean on existing tools and documentation to maintain '''[[reproducible builds|reproducibility]]''' of your project. |
− | * You must abide by the [[Fiji contribution requirements]]. | + | * Your project will always be compatible with the latest Fiji distribution. |
− | * You must rely on a Fiji | + | * [[Travis]] automatically tests your project for errors, deploying successful builds to the [[SciJava Maven repository]]. |
+ | | style="background: #dfd; vertical-align: top" | | ||
+ | * You must abide by the '''[[Fiji contribution requirements]]'''. | ||
+ | * You must rely on a Fiji maintainer (for now) 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 98: | ||
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. | ||
− | + | {| 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 96: | Line 117: | ||
* All of '''[[ImageJ]]''', '''[[Fiji]]''' and related '''[[SciJava]]''' projects are '''[[Source code|hosted on GitHub]]'''. | * All of '''[[ImageJ]]''', '''[[Fiji]]''' and related '''[[SciJava]]''' projects are '''[[Source code|hosted on GitHub]]'''. | ||
| style="background: #dfd; vertical-align: top" | | | style="background: #dfd; vertical-align: top" | | ||
− | * Git has a steep learning curve—the '''[https:// | + | * Git has a steep learning curve—the '''[https://desktop.github.com/ GitHub Desktop]''' client makes things easier. |
− | | | + | |- |
− | + | | colspan="3" style="background: white; border: none; height: 1em" | | |
− | | colspan="3" style="background: | + | |- |
+ | | colspan="3" style="background: #afa" | '''Host on GitHub in the Fiji organization (for [[Fiji contribution requirements|extensions distributed with Fiji]])''' | ||
|- | |- | ||
− | |'''Steps''' | + | | style="background: #dfd" |'''Steps''' |
− | |'''Advantages''' | + | | style="background: #dfd" |'''Advantages''' |
− | |'''Disadvantages''' | + | | style="background: #dfd" |'''Disadvantages''' |
|- | |- | ||
− | | style="vertical-align: top" | | + | | style="background: #dfd; vertical-align: top" | |
− | * Request a Fiji | + | * Request a '''[[Governance|Fiji maintainer]]''' create a repository for you and add you as a contributor. |
− | * | + | * Meet the '''[[Fiji contribution requirements]]'''. |
− | | style="vertical-align: top" | | + | | style="background: #dfd; vertical-align: top" | |
* All the benefits of GitHub. | * All the benefits of GitHub. | ||
− | * A Fiji maintainer helps | + | * A '''[[Governance|Fiji maintainer]]''' helps you to manage your project. |
− | | style="vertical-align: top" | | + | | style="background: #dfd; 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 151: | ||
* 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 139: | Line 165: | ||
* SourceForge predates GitHub; some people prefer it. | * SourceForge predates GitHub; some people prefer it. | ||
| style="vertical-align: top" | | | style="vertical-align: top" | | ||
− | * The interface is not as powerful as GitHub and BitBucket: | + | * The interface is not as powerful as GitHub and BitBucket: |
− | * The collaboration features are vastly inferior. | + | ** 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 [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 161: | Line 192: | ||
* No easy submission of patches. | * No easy submission of patches. | ||
* No finding the code in web searches. | * No finding the code in web searches. | ||
− | * No | + | * No reading the change logs to understand why changes were made. |
− | * No | + | * 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. | ||
|} | |} | ||
Line 168: | Line 205: | ||
Useful extensions deserve corresponding documentation explaining how to use them. | Useful extensions deserve corresponding documentation explaining how to use them. | ||
− | + | {| 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 184: | Line 221: | ||
| style="background: #dfd; vertical-align: top" | | | style="background: #dfd; vertical-align: top" | | ||
- | - | ||
− | | | + | |- |
− | + | | 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 197: | Line 235: | ||
| style="vertical-align: top" | | | style="vertical-align: top" | | ||
* The [http://imagejdocu.tudor.lu/ ImageJ Information and Documentation Portal] predates the ImageJ wiki, and many extensions are still primarily documented there. | * The [http://imagejdocu.tudor.lu/ ImageJ Information and Documentation Portal] predates the ImageJ wiki, and many extensions are still primarily documented there. | ||
− | * The IIDP is a fairly [http://imagejdocu.tudor.lu/doku.php?id=start&do=recent active] wiki. | + | * The IIDP is a fairly [http://imagejdocu.tudor.lu/doku.php?id=start&do=recent active] wiki (but not [[Special:RecentChanges|compared to this one]]!). |
* The ImageJ developers hope to unify these two wikis in the future. | * The ImageJ developers hope to unify these two wikis in the future. | ||
| style="vertical-align: top" | | | style="vertical-align: top" | | ||
Line 203: | Line 241: | ||
* 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 212: | Line 252: | ||
| style="vertical-align: top" | | | style="vertical-align: top" | | ||
* Prepare an HTML page modeled after the [http://imagej.net/plugins/index.html list of ImageJ 1.x plugins]. | * Prepare an HTML page modeled after the [http://imagej.net/plugins/index.html list of ImageJ 1.x plugins]. | ||
− | * Email it to | + | * Email it to {{Person|Rasband}}, the developer of ImageJ 1.x, and sole maintainer of the [http://imagej.net/index.html ImageJ 1.x website]. |
| style="vertical-align: top" | | | style="vertical-align: top" | | ||
* Listed on the ImageJ 1.x website. | * Listed on the ImageJ 1.x website. | ||
Line 219: | Line 259: | ||
* 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''' | ||
Line 232: | Line 274: | ||
* Nonstandard location. Users may have trouble finding your documentation. | * Nonstandard location. Users may have trouble finding your documentation. | ||
* Not collaborative. No one else can improve the 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]] | + | * 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!) |
|} | |} | ||
[[Category:Development]] | [[Category:Development]] |
Latest revision as of 20:11, 21 August 2019
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.
- 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 |
|
|
|
|
Distribute it as part of Fiji | |||
Steps | Installation | Advantages | Disadvantages |
|
|
|
|
Serve it from a website as a download | |||
Steps | Installation | Advantages | Disadvantages |
|
|
|
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 |
|
|
|
Host on GitHub in the Fiji organization (for extensions distributed with Fiji) | ||
Steps | Advantages | Disadvantages |
|
|
|
Host on BitBucket | ||
Steps | Advantages | Disadvantages |
|
|
|
Host on SourceForge | ||
Steps | Advantages | Disadvantages |
|
|
|
Serve it from a website as a download | ||
Steps | Advantages | Disadvantages |
|
|
|
Documenting your extension
Useful extensions deserve corresponding documentation explaining how to use them.
Create an ImageJ wiki page | ||
Steps | Advantages | Disadvantages |
|
|
- |
Use the ImageJ Information and Documentation Portal (IIDP) | ||
Steps | Advantages | Disadvantages |
|
|
|
Add a page to the ImageJ 1.x website | ||
Steps | Advantages | Disadvantages |
|
|
|
Create your own webpage elsewhere | ||
Steps | Advantages | Disadvantages |
(Varies) |
|
|