Contributors guidelines

From OTBWiki
Jump to: navigation, search

This page deals with guidelines to contribute code and features to the Orfeo ToolBox. Some of this content is also present in the SoftwareGuide There are three ways of contributing code to OTB:

  • Bug fixes, small changes and documentation. These are accepted as GitHub pull requests against the develop branch. They will be reviewed by the core team. You are also welcome to send a patch to the developers mailing list (otb-developpers@googlegroups.com)
  • Remote modules
  • Large contributions (new features, refactoring, etc.) via the RFC process

Caution

  • This page has to be reviewed by PSC
  • Some guidelines only apply after modularization is completed

Contributions through Remote Modules

This is the prefered way if your contribution is about adding new classes or application to bring new features to OTB. Please also refer to ITK guidelines for remote modules.

What are remote modules?

Remote modules are just like regular modules, except they are not distributed inside OTB source code.

In the Modules/Remote folder of the OTB sources, you can add any number of directories containing valid modules. You will then be able to activate those module through CMake configuration, and build them.

But there is more. Let assume that you have a valid remote module, hosted somewhere on a Git repository. We can add a special CMake file in the Modules/Remote that will tell CMake that this remote module is available, and can be activated during CMake configuration. Upon activation, CMake will first checkout the remote module source code into Modules/Remote, and then build it as a regular module.

But there is more. Once the CMake file describing your module is added into Remote/Modules, you can benefit from OTB development services just like any other module: dashboard build, packaging, doxygen documentation ...

To make it short, by contributing a remote module:

  • You still host the code of your contribution, which is not mixed with other parts of OTB,
  • Any user building OTB will be able to fetch and build your module,
  • Your module will be built on dashboard, packaged for official releases and documented by OTB automatic documentation processes,
  • You do not need permissions to push changesets on OTB repositories.

How to get your remote module inside OTB?

  1. Follow the instructions on writing a remote module in order to have a working remote module inside your local source code tree.
  2. Host the remote module code on a publicly available git repository. If you do not have access to a git server, bitbucket or github can provide this service for you.
  3. Write a short email to the otb-developers list, detailing your contributed remote module, and providing the cmake file to add into Modules/Remote so as to get it into OTB, as well as evidence that you comply with the remote module policy (see bellow).
  4. Remote module acceptance policy compliance will be checked by the otb-developers list,
  5. Create a wiki page for your remote module here. A sample template is given here.
  6. Acceptance of remote module is submitted to vote on otb-developers (to be reviewed by PSC).

If accepted, your CMake file will be placed into the Modules/Remote folder inside OTB source tree.

During the OTB release process, all module complying with the remote module release policy will be packaged along with standard modules.

A remote module can be removed from Modules/Remote (this only requires to remove the CMake file describing it), if:

  • It does no longer comply with the remote module acceptance policy (in which case the decision is submitted to vote on otb-developers),
  • The author of the remote module ask to remove it.

Remote module acceptance policy

So as to get your module accepted as an official remote module, you should comply with the following:

  • Remote module source code should be hosted on a publicly available Git repository
  • Author of the remote module should be identified and registered to otb-developers mailing list
  • Author of the remote module accepts to be contacted by developers or users regarding issues with his module (on a best effort basis),
  • Remote module source code should comply with OTB style as much as possible,
  • Remote module source code should be documented using doxygen tags,
  • Remote module should provide a minimal set of tests to ensure build of template code and basic non-regression testing,
  • Remote module should come with a form of documentation (website, publication, readme file ...)
  • Remote module should not embed code from any third party software (unless strong arguments are given by the author, in which case an exception can be made),
  • Remote module should avoid depending on new third parties if possible,
  • Remote module author should be the copyright owner and comply with licences of any third party, which in turn should comply with terms of OTB licence (to be reviewed by PSC)
  • Author of remote module should provide a small description of the remote module to be added on OTB website.

An internal module should never depend on a remote module whatsoever.

Remote module release policy

During the OTB release process, a remote module will be included in source and binary packages if:

  • Dashboard submission exist and show that the remote module:
    • Builds on all plateform,
    • Passes all tests on the reference platform,
    • Does not have any test crashing (i.e. failing with core dump or memory issues) on remaining platform
  • The remote module complies with the remote module acceptance policy at the time of the Release Candidate

Developers will notify remote modules authors of existing issues at Release Candidate. If by 3 day to the final release dates, some issues listed above still exist, the remote module will be removed from the release source and binary packages.

Moreover, remote module bringing in new third party dependencies will not be included in binary packages.

Contributing code to OTB sources

Some contributions can not be packaged as remote modules (for instance contributions to existing modules), or might as well be integrated directly in Orfeo ToolBox source code. The process for such contribution depends on the permissions granted to the author on our git repository.

Step 1: RFC submission and acceptance

All major changes should be approved by the Project Steering Committee by following the RFC submission process. Small changes such as bugfixes, compilation warnings and errors fixes, typos, and small optimisation or refactoring do not require to follow this process however they should be advertised and discussed on otb-developers list.

Step 2: Writing code

Development should follow OTB git workflow as described HERE.

Development should follow OTB coding style as described HERE.

Step 3: merging to develop branch

If the author has write permissions on Orfeo ToolBox git repositories

Prior to any merge in the develop branch, the release manager approval should be requested and obtained. The release manager will give its approval by following the feature branch merge acceptance checklist.

If the author does not have write permissions on Orfeo ToolBox git repository

It is advised that you use the pull request mechanism of github in such case, using the official Orfeo ToolBox github repository. Once the pull request is posted, please write to otb-developers to call for review and acceptance of the release manager.