ImageJ

{{Notice | There is another good way to distribute your extension: your own [[update site]]. See the [[Distribution]] page for details.}}
{{FijiMenu}}Distributing your software component as part of [[Fiji]] is an effective way to immediately and easily put it into the hands of many users, as well as to actively participate in the community of ImageJ software development. However, doing so comes with a few corresponding rules.

The following document describes these requirements, as well as associated best practices, for shipping your component as part of the [[Fiji]] update site.

= Definition =

A "core" [[Fiji]] project is one distributed on the [http://update.fiji.sc Fiji update site]. Such projects are subject to the requirements discussed below. Conversely, if you distribute your [[ImageJ]] extension on a separate update site, this page does not apply.

= Requirements =

== Freely accessible source code ==

A key principle of the Fiji project is:

:''If you want to go fast, go alone. If you want to go far, go together.''
: - ''African proverb''

There are many corollaries to this wisdom, the most prominent: if you write software in your endeavor to discover new insights, [[Open Source]] is the way that brings you farthest. Withholding the source code—like any other method to obstruct other researchers' work, e.g. refusing to share materials and methods—will [[Why Closed-Source Is Wrong|invariably have the opposite effect]] in the long run. Likewise, working with interested parties to improve one's project will invariably lead to a much better and stronger result.

As such, components distributed with Fiji must be licensed in a way [https://www.gnu.org/licenses/license-list.html compatible with the GNU General Public License].

== Source hosted on GitHub ==

Core Fiji development takes place on [[GitHub]]. This ensures continuity and visibility, and facilitates collaboration.

There are two possibilities for where to host your project:

# '''Standard.''' Repository is hosted in the [https://github.com/fiji fiji organization], or a descendant organization (e.g., [https://github.com/trakem2 trakem2]). [[Governance|Fiji maintainers]] help maintain the project.
# '''External.''' Repository is hosted in a GitHub organization you control. You alone maintain the project (though Fiji maintainers may submit PRs to help).

=== Standard projects ===

The following criteria apply to projects hosted in the [https://github.com/fiji fiji organization]:
* Each component (i.e., JAR file) lives in its own repository.
* Components use [[Maven]] to build:
** As single-module projects
** With the standard Maven directory layout
** Extending the [[Architecture#Maven_component_structure|pom-scijava parent POM]]
* Components use the groupId <code>sc.fiji</code>.
* Components are [[Versioning|versioned according to SemVer]].
* The project uses [[Issues|GitHub Issues]] for issue tracking.
* The project has a dedicated page here on the ImageJ wiki.
* The [[Governance|Fiji maintainers]] may make commits and [[Releases|release new versions]] of the component as needed, so that Fiji as a whole continues to work as intended.
* The <code>master</code> branch is considered ''release ready'' at all times, meaning it compiles with passing tests, and is ready for downstream consumption.

=== External projects ===

Projects that reside outside the [https://github.com/fiji fiji organization] are not subject to the requirements above. But it is then the project maintainer's responsibility to ensure the project continues to function properly in up-to-date installations of Fiji. This might entail code changes as ImageJ and Fiji evolve.

== Continuous integration: Travis CI ==

To verify that the Fiji components build without problems, and that all regression tests pass, every Fiji project's source code repository is connected to a [[Travis CI]] job that builds and tests the source code, and deploys the [[#Maven artifacts|Maven artifacts]], whenever a new revision is made available.

Have a look at the [[Travis]] page for instructions on setting it up.

== Versioning and dependency convergence ==

Most Fiji projects use the [[Versioning|SemVer versioning scheme]]: a standard to encourage API consistency without obstructing API improvements.

The minimum requirement for core Fiji projects is to abide by the '''MAJOR''' digit portion of [http://semver.org/ SemVer]—i.e., if the first digit of the version string increases, it means that the new version is ''not'' backwards compatible with the old version. Conversely, if any later digit of the version string increases, it means that the new version ''is'' backwards compatible.

This requirement exists to facilitate automated tooling for dependency convergence: the use of compatible dependency versions across all of Fiji. When two (or more) components of Fiji depend on different versions of the same component, it must be possible to verify which version is newer, and whether the newer version is backwards compatible with the old one. As long as the newest required dependencies are indeed backwards compatible, those dependencies are said to ''converge''.

From example, Apache Commons Math v3.x breaks backwards compatibility with Apache Commons Math v2.x. Since both versions share the same package and class names, only one of these versions can be shipped with Fiji. Therefore, all components of Fiji must rely on the same major version: either v2 or v3.

In general, if the rest of the Fiji distribution upgrades to a new major version of a library on which your component depends, your component must also be upgraded to use the new version. Such decisions are typically reached after [[Communication|discussion on public channels]].

=== Best practice: version constants ===

Many plugins in Fiji contain explicit version constants. Without [[Maven]], in-code constants may make sense as a way to track compatibility. But by Mavenizing for contribution to Fiji, the pom.xml provides a standard mechanism for versioning, allowing migration away from constants in the source code.

Versioning through the pom.xml has several advantages to facilitate [[Reproducibility|reproducible builds]], including:

* Standardized scripts to increment versions appropriately.
* No risk of accidentally double-releasing a given version.
* Users and developers see the same version information.

Furthermore, for backwards-compatibility a version can be automatically deduced:

* From the POM. This is the most reliable option. For convenience, [https://github.com/scijava/scijava-common scijava-common] provides a utility class to assist in version retrieval: [https://github.com/scijava/scijava-common/blob/scijava-common-2.39.0/src/main/java/org/scijava/util/VersionUtils.java#L51 VersionUtils].
* Alternatively, the [http://docs.oracle.com/javase/7/docs/api/java/lang/Package.html#getSpecificationVersion%28%29 specification] or [http://docs.oracle.com/javase/7/docs/api/java/lang/Package.html#getImplementationVersion%28%29 implementation] version can be used - for example, as in the [https://github.com/fiji/LSM_Reader/commit/a6b26290ad71667efd75d77f3eef95d445d6eaff LSMReader]. Core Fiji libraries follow a convention of setting these versions to match the pom version, and they are set at the manifest level to ensure they are they same for all packages in a given component. '''However''', the two versions are allowed to differ - each package is allowed its own specification and implementation version! Furthermore, classes in a default package will not be able to retrieve either version. So these functions can not be relied on as a general solution.

== Maven artifacts ==

[[Fiji]] and related [[SciJava]] software uses [[Maven]], an industry standard to declare metadata about a project, to build projects using said metadata, and to ''deploy'' the resulting artifacts to a [[Architecture#Maven_repositories|Maven repository]]. Such repositories are essentially for developers what [[update sites]] are for users.

* The minimum requirement for core Fiji projects is to use a build system (e.g., [[Maven]] or Gradle) that automatically deploys required artifacts to the [http://maven.imagej.net/ ImageJ Maven repository], such that they can be consumed by downstream code, including other Fiji projects. Required artifacts to deploy include the main JAR and POM files, <code>-tests</code> JAR, <code>-sources</code> JAR and <code>-javadoc</code> JAR.
* To facilitate this, most Fiji projects inherit a common Maven configuration from the [https://github.com/fiji/pom-fiji pom-fiji] parent project. This configuration ensures that not only the compiled ''.jar'' files are deployed, but also the Javadocs and the sources. Therefore, it is strongly encouraged to extend this parent; see the [[Architecture#Maven_component_structure|Maven component structure]] section for details.
* All of Fiji's components are deployed by [[Travis CI]] to the [[Architecture#Maven_repositories|ImageJ Maven repository]] or to [http://oss.sonatype.org/ OSS Sonatype]. That way, all Fiji components can be added easily as dependencies to downstream projects.
* All Fiji components are declared in the toplevel [https://github.com/fiji/fiji fiji] project's POM as dependencies, and declared in the [https://github.com/fiji/pom-fiji pom-fiji] parent as ''managed dependencies'', as part of Fiji's [[Architecture#Bill_of_Materials|Bill of Materials]].

= Guidelines =

The following guidelines are less technical and more philosophical, but represent best practice for core Fiji components.

== Open development process ==

Developers of Fiji components should invite others to contribute. That entails welcoming developers, acknowledging and working on pull requests, encouraging improvements, working together, enhancing upon each others' work, share insights, etc.

To leverage the power of [[open source]], the default for discussions should be to use [[Communication|public channels]]. In other words, the question to ask should be "Is there any good reason why this conversation should be private?" instead of the opposite.

== Active bug management ==

Bug reports need to be acknowledged, participation in resolving bugs should be encouraged whenever possible, bugs should not go uncommented for months (we all have times when we are busy e.g. writing a paper; a little message helps the involved people understand), explanations are due when bugs go unresolved for years, etc

== Reusability and reliability ==

Whenever possible, source code should be reused. If necessary, improve the existing source code. Only rewrite from scratch when absolutely necessary.

Make code reusable, i.e. define APIs to use the functionality. This requires a little bit of discipline so that third parties can rely on the interfaces.

== Regression tests ==

Writing regression tests is [https://github.com/junit-team/junit/wiki/Getting-started easy]: create a class in the ''src/test/java/'' directory structure and annotate methods with ''@Test'', testing for various [https://github.com/junit-team/junit/wiki/Assertions assertions] (the most common ones are ''assertEquals()'', ''assertTrue()'' and ''assertNotNull()'').

In particular when fixing a bug, it is a good idea to write a regression test ''first'', making sure that it actually fails. After that, one should develop the fix, getting a cozy and warm feeling once the regression test passes.

== Separation of concerns ==

New features should be put into the appropriate component. E.g., when adding a general purpose utility, consider contributing to [[SciJava Common]] or [[ImageJ Common]] instead of bundling it with your specific extension.

= Examples =

The following table provides a few examples of how various Fiji components are structured.

{| class="wikitable"
| colspan=5 style="text-align: center" | '''Basics'''
| colspan=2 style="text-align: center" | '''[[GitHub]]'''
| colspan=1 style="text-align: center" | '''[[Maven]]'''
|-
| '''Classification'''
| '''Component'''
| '''Core?<sup>1</sup>'''
| '''Update site'''
| '''License<sup>2</sup>'''
| '''Organization'''
| '''Repository'''
| '''groupId'''
|-
| rowspan=4 | '''Standard'''
| [[3D Viewer]]
| style="text-align: center" | {{Yes}}
| [http://update.fiji.sc/ Fiji]
| [[GPLv3]]
| [https://github.com/fiji fiji]
| {{GitHub | org = fiji | repo = 3D_Viewer | label = 3D_Viewer}}
| <code>sc.fiji</code>
|-
| [[Coloc 2]]
| style="text-align: center" | {{Yes}}
| [http://update.fiji.sc/ Fiji]
| [[GPLv3]]
| [https://github.com/fiji fiji]
| {{GitHub | org = fiji | repo = Colocalisation_Analysis | label = Colocalisation_Analysis}}
| <code>sc.fiji</code>
|-
| [[Simple Neurite Tracer]]
| style="text-align: center" | {{Yes}}
| [http://update.fiji.sc/ Fiji]
| [[GPLv3]]
| [https://github.com/fiji fiji]
| {{GitHub | org = fiji | repo = Simple_Neurite_Tracer | label = Simple_Neurite_Tracer}}
| <code>sc.fiji</code>
|-
| [[TrackMate]]
| style="text-align: center" | {{Yes}}
| [http://update.fiji.sc/ Fiji]
| ?
| [https://github.com/fiji fiji]
| {{GitHub | org = fiji | repo = TrackMate | label = TrackMate}}
| <code>sc.fiji</code>
|-
| rowspan=2 | '''External'''
| [[Sholl Analysis]]
| style="text-align: center" | {{Yes}}
| [http://update.fiji.sc/ Fiji]
| [[GPLv3]]
| [https://github.com/tferr tferr]
| {{GitHub | org = tferr | repo = ASA | label = ASA}}
| <code>ca.mcgill</code>
|-
| [[Bio-Formats]]
| style="text-align: center" | {{Yes}}
| [http://update.fiji.sc/ Fiji]
| [[GPLv2]]
| [https://github.com/openmicroscopy openmicroscopy]
| {{GitHub | org = openmicroscopy | repo = bioformats | label = bioformats}}
| <code>ome</code>
|-
| rowspan=2 | '''Subproject'''
| [[BigDataViewer]]
| style="text-align: center" | {{Yes}}
| [http://update.fiji.sc/ Fiji]
| [[GPLv3]]
| [https://github.com/bigdataviewer bigdataviewer]
| {{GitHub | org = bigdataviewer | repo = bigdataviewer_fiji | label = bigdataviewer_fiji}}
| <code>sc.fiji</code>
|-
| [[TrakEM2]]
| style="text-align: center" | {{Yes}}
| [http://update.fiji.sc/ Fiji]
| [[GPLv3]]
| [https://github.com/trakem2 trakem2]
| {{GitHub | org = trakem2 | repo = TrakEM2 | label = TrakEM2}}
| <code>sc.fiji</code>
|-
| rowspan=3 | '''Third party'''
| [[Cookbook]]
| style="text-align: center" | {{No}}
| [http://sites.imagej.net/Cookbook/ Cookbook]
| [[Cookbook#Credits|Various]]
| [https://github.com/fiji fiji]
| {{GitHub | org = fiji | repo = cookbook | label = cookbook}}
| <code>sc.fiji</code>
|-
| [[MaMuT]]
| style="text-align: center" | {{No}}
| [http://sites.imagej.net/MaMuT/ MaMuT]
| [[GPLv3]]
| [https://github.com/fiji fiji]
| {{GitHub | org = fiji | repo = MaMuT | label = MaMuT}}
| <code>sc.fiji</code>
|-
| [[SLIM Curve]]
| style="text-align: center" | {{No}}
| [http://sites.imagej.net/SLIM-Curve/ SLIM-Curve]
| [[GPLv3]]
| [https://github.com/slim-curve slim-curve]
| {{GitHub | org = slim-curve | repo = slim-plugin | label = slim-plugin}}
| <code>slim-curve</code>
|}
<sup>1</sup> A "core" project is one distributed on the Fiji update site. These projects are subject to the requirements discussed on this page.
<br><sup>2</sup> See the [[Licensing]] page for further details.

[[Category:Fiji]]