Difference between revisions of "Distribution"
(→Distributing your extension: Embolden links, for readability) |
(Fix typo) |
||
(19 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
− | __NOTOC__{{ | + | __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''' | ||
Line 6: | Line 6: | ||
== Best practices == | == Best practices == | ||
− | Here is a quick summary of the options | + | Here is a quick summary of the most recommended options: |
* '''Distribution.''' | * '''Distribution.''' | ||
** A) '''[[How to set up and populate an update site|create your own update site]]'''; or | ** A) '''[[How to set up and populate an update site|create your own update site]]'''; or | ||
Line 14: | Line 14: | ||
** Host it on '''[[GitHub]]'''. | ** Host it on '''[[GitHub]]'''. | ||
** Use '''[[Maven]]''' to build and SemVer for '''[[versioning]]'''. | ** Use '''[[Maven]]''' to build and SemVer for '''[[versioning]]'''. | ||
+ | ** Use '''[[Travis]]''' for continuous integration and artifact deployment to the [[SciJava Maven repository]]. | ||
* '''Documentation.''' | * '''Documentation.''' | ||
** Create a page here on the '''[http://imagej.net/ ImageJ Wiki]'''. | ** Create a page here on the '''[http://imagej.net/ ImageJ Wiki]'''. | ||
Line 32: | 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 45: | Line 46: | ||
| 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|upgrade 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|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" | | ||
Line 56: | Line 58: | ||
|- | |- | ||
| style="background: #dfd; vertical-align: top" | | | style="background: #dfd; vertical-align: top" | | ||
− | * | + | * Make a post on the '''[[Forum|ImageJ forum]]''' to initiate a request. |
| style="background: #dfd; 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="background: #dfd; 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 '''[[Governance|Fiji maintainer]]''' will help you to manage your project. | * A '''[[Governance|Fiji maintainer]]''' will help you to manage your project. | ||
− | * | + | * You can lean on existing tools and documentation to maintain '''[[reproducible builds|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]]. | ||
| style="background: #dfd; 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]]'''. | ||
Line 113: | 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 [[Governance|Fiji maintainer]] create a repository for you and add you as a contributor. | + | * 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 [[Governance|Fiji maintainer]] helps you to manage your project. | + | * 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 188: | 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 225: | 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 242: | 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) |
|
|