Difference between revisions of "Distribution"
(Tweak further) |
(Fix typo) |
||
(23 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: white; border: none; height: 1em" | | | colspan="4" style="background: white; border: none; height: 1em" | | ||
|- | |- | ||
− | | colspan="4" style="background: | + | | 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: white; border: none; height: 1em" | | ||
Line 80: | 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 99: | 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: 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: white; border: none; height: 1em" | | ||
Line 174: | 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 181: | 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 211: | 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 228: | 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. |
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) |
|
|