ITK/Policy and Procedures for Adding Remote Modules: Difference between revisions

From KitwarePublic
< ITK
Jump to navigationJump to search
 
(9 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Remote modules are downloaded at CMake configuration time into the ''Remote'' module group, i.e. into the ''Modules/Remote'' directory of the repository tree.  A Remote Module can be enabled by setting the target ''Fetch_<module name>'' CMake configuration variable to ''ON''.
Remote modules are downloaded at CMake configuration time into the ''Remote'' module group, i.e. into the ''Modules/Remote'' directory of the repository tree.  A Remote Module can be enabled by setting the target ''Module_<module name>'' CMake configuration variable to ''ON'' just like other ITK Modules.


== Purpose of Remote Modules ==
= Purpose of Remote Modules =


The new modularization resulting from the ITKv4 effort provides a new level of
The new modularization resulting from the ITKv4 effort provides a new level of
Line 26: Line 26:
In general, the Remote Module system is medium for articles submitted in the Insight Journal to see greater adoption or transition into the toolkit.
In general, the Remote Module system is medium for articles submitted in the Insight Journal to see greater adoption or transition into the toolkit.


== Policy for Adding and Removing Remote Modules ==
= Policy for Adding and Removing Remote Modules =


A module can be added to the list of remotes if it satifies the following criteria:
A module can be added to the list of remotes if it satifies the following criteria:
Line 33: Line 33:
* There is a nightly build against ITK master on the CDash dashboard that builds and passes tests successfully.
* There is a nightly build against ITK master on the CDash dashboard that builds and passes tests successfully.
* A name and contact email exists for the dashboard build.  The maintainer of the dashboard build does not necessarily need to be the original author of the Insight Journal article.
* A name and contact email exists for the dashboard build.  The maintainer of the dashboard build does not necessarily need to be the original author of the Insight Journal article.
* The license should be compatible with the rest of the toolkit.  That is, it should be an [http://opensource.org/licenses OSI approved license] without copyleft or non-commercial restrictions.  Ideally, it should be an Apache 2.0 license assigned to the "Insight Software Consortium" as found in the rest of the toolkit.


At the beginning of the release candidate phase of a release, maintainers of failing module dashboard builds will be contacted.  If a module's dashboard submission is still failing at the last release candidate tagging, it will be removed before the final release.
At the beginning of the release candidate phase of a release, maintainers of failing module dashboard builds will be contacted.  If a module's dashboard submission is still failing at the last release candidate tagging, it will be removed before the final release.
Line 40: Line 41:
At no time in the future should a module in the main repository depend on Remote module.
At no time in the future should a module in the main repository depend on Remote module.


== Procedure for Adding a Remote Module ==
= Procedure for Adding a Remote Module =


#  Publish an open access article describing the module in an online journal like the [http://insight-journal.org/ Insight Journal].
#  Publish an open access article describing the module in an online journal like the [http://insight-journal.org/ Insight Journal].
#  [[ITK/Git/Dashboard|Set up a nightly dashboard submission]] for the module against the master branch of ITK.
#  [[ITK/Git/Develop|Submit a Gerrit patch]] that adds a file named Modules/Remote/<module name>.remote.cmake.  This file must have the following:
#  [[ITK/Git/Develop|Submit a Gerrit patch]] that adds a file named Modules/Remote/<module name>.remote.cmake.  This file must have the following:
## Dashboard maintainer name and email in the comments.
## Dashboard maintainer name and email in the comments.
## A call to the itk_fetch_module CMake function (documented in CMake/ITKModuleRemote.cmake) whose arguments are:
## A call to the itk_fetch_module CMake function (documented in CMake/ITKModuleRemote.cmake) whose arguments are:
### The name of the remote module; Note that the name should NOT contain the "ITK" prefix.
### The name of the remote module; '''Note that in each <remote module name>.remote.cmake, the first argument of the function itk_fetch_module() is the name of the remote module, and it has to be consistent with the module name defined in the corresponding itk-module.cmake. To better distinguish the remote modules from the internal ITK modules, the names of the remote modules should NOT contain the "ITK" string prefix.'''
### A short description of the module with the handle to the open access article.
### A short description of the module with the handle to the open access article.
### URL's describing the location and version of the code to download.
### URL's describing the location and version of the code to download. The version should be a specific hash or tag (not "master").
#  Send a message to the [http://itk.org/ITK/help/mailing.html insight-users and insight-developers mailing lists] with the subject "New Remote Module: <module name>" and with a body that has pointers to the nightly dashboard submission and the Gerrit Change-Id.

Latest revision as of 20:34, 8 September 2016

Remote modules are downloaded at CMake configuration time into the Remote module group, i.e. into the Modules/Remote directory of the repository tree. A Remote Module can be enabled by setting the target Module_<module name> CMake configuration variable to ON just like other ITK Modules.

Purpose of Remote Modules

The new modularization resulting from the ITKv4 effort provides a new level of organization and extensibility to the toolkit. A module that follows the directory layout and has the required ITK modularization CMake content that is placed in one of the Module Groups of the repository will be automatically picked up and added to the build.

While individuals or organizations can work on their own private modules and optionally make these modules publically available, the listing of Remote modules in the main ITK repository has two benefits:

  1. Amalgation of modules prevents the need for module consumers to spend an extended effort searching for algorithm implementations.
  2. Integration of the Remotes into the repository make it trivial to download the module and automatic fetch it in a build.

Good candidates for addition to the collection can be

  • ITK based code that have additional third-party dependencies not bundled with the toolkit.
  • New algorithms or implementations seeking greater exposure and adoption.
  • Algorithms that hope to eventually be integrated into the toolkit.
  • Niche algorithms with limited application.
  • Modules in progress that do not yet have the test coverage and cross-platform standards required by the main toolkit.

In general, the Remote Module system is medium for articles submitted in the Insight Journal to see greater adoption or transition into the toolkit.

Policy for Adding and Removing Remote Modules

A module can be added to the list of remotes if it satifies the following criteria:

  • There is an article in an open access journal (such as the Insight Journal) describing the theory behind and usage of the module.
  • There is a nightly build against ITK master on the CDash dashboard that builds and passes tests successfully.
  • A name and contact email exists for the dashboard build. The maintainer of the dashboard build does not necessarily need to be the original author of the Insight Journal article.
  • The license should be compatible with the rest of the toolkit. That is, it should be an OSI approved license without copyleft or non-commercial restrictions. Ideally, it should be an Apache 2.0 license assigned to the "Insight Software Consortium" as found in the rest of the toolkit.

At the beginning of the release candidate phase of a release, maintainers of failing module dashboard builds will be contacted. If a module's dashboard submission is still failing at the last release candidate tagging, it will be removed before the final release.

Module names must be unique.

At no time in the future should a module in the main repository depend on Remote module.

Procedure for Adding a Remote Module

  1. Publish an open access article describing the module in an online journal like the Insight Journal.
  2. Submit a Gerrit patch that adds a file named Modules/Remote/<module name>.remote.cmake. This file must have the following:
    1. Dashboard maintainer name and email in the comments.
    2. A call to the itk_fetch_module CMake function (documented in CMake/ITKModuleRemote.cmake) whose arguments are:
      1. The name of the remote module; Note that in each <remote module name>.remote.cmake, the first argument of the function itk_fetch_module() is the name of the remote module, and it has to be consistent with the module name defined in the corresponding itk-module.cmake. To better distinguish the remote modules from the internal ITK modules, the names of the remote modules should NOT contain the "ITK" string prefix.
      2. A short description of the module with the handle to the open access article.
      3. URL's describing the location and version of the code to download. The version should be a specific hash or tag (not "master").