CONTRIBUTING.md 9.83 KB
Newer Older
1
# How to contribute to Orfeo ToolBox ?
2 3 4 5 6 7 8 9 10 11 12 13 14 15

Thank you for taking the time to contribute to OTB! This document will guide you
through the workflow and best practices you need to know to send your
contribution.

There are many ways to contribute to OTB:

* [Reporting a bug](#reporting-bugs)
* [Making a feature request](#feature-requests-and-discussions)
* [Improving documentation](#documentation-improvements)
* [Contributing code (C++, Python, CMake, etc.)](#code-contribution)
* [Publishing a remote module](#remote-modules)

Our main workflow uses GitLab for source control, issues and task tracking. We
16
use a self-hosted GitLab instance:
17 18 19

[`https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb`](https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb)

20
Remember to check out also our [forum](https://forum.orfeo-toolbox.org/),
21 22 23 24 25
where we discuss some features, improvements and high level project planning.
You are welcome to ask questions there as a beginner or future OTB contributor!

## Reporting bugs

26
If you have found a bug, you can first [search the existing issues](https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/issues?label_name%5B%5D=bug)
27 28
to see if it has already been reported.

29
If it's a new bug, please [open a new issue on GitLab](https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/issues/new).
30 31 32 33 34 35
The 'Bug' issue template will help you provide all important information and
help fixing the bug quicker. Remember to add as much information as possible!

## Feature requests and discussions

Feature requests are welcome! Generally you are welcome to simply [open an issue](https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/issues)
36 37
and discuss your idea there. For more complex requests there is an issue
template for in depth description called 'Request for Comments'.
38 39 40 41


## Documentation improvements

42 43
The main OTB documentation is
the [CookBook](https://www.orfeo-toolbox.org/CookBook/).  The source is
44 45 46 47
hosted in the main OTB repository in the `Documentation/` directory. Then, to
contribute documentation use the same workflow as for code contributions (see
below).

48 49
See also the "Compiling documentation" section of the CookBook
for help on building the Sphinx source.
50 51 52 53 54 55 56 57

## Code contribution

The OTB workflow is based on GitLab [Merge Requests](https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html).
Clone the repository, create a feature branch, commit your changes, push the
feature branch to a fork (or the main repository if you are a core developer),
then send a merge request.

58 59
Note that we also accept PRs on our [GitHub mirror](https://github.com/orfeotoolbox/OTB)
which we will manually merge.
60

61 62
Feature branches are tested on multiple platforms on the OTB
[CI infrastructure](https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/pipelines). 
63

64
Caveat: even if the CI build on develop branch is broken, it is not
65
allowed to push fixes directly on develop. The developer trying to fix the
66 67
build should create a merge request and submit it for review. Direct push to
develop without review must be avoided.
68

69 70 71 72
### Commit message

On your feature branch, write a good [commit message](https://xkcd.com/1296/):
short and descriptive. If fixing an issue or bug, put the issue number in the
73
commit message so that GitLab can [cross-link it](https://docs.gitlab.com/ce/user/project/issues/crosslinking_issues.html).
74
You can prefix your commit message with an indicating flag (DOC, BUG, PKG,
75
TEST, SuperBuild, etc.).
76

77 78 79 80 81 82 83 84 85 86
Standard prefixes for OTB commit messages:

    BUG: Fix for runtime crash or incorrect result
    COMP: Compiler error or warning fix
    DOC: Documentation change
    ENH: New functionality
    PERF: Performance improvement
    STYLE: No logic impact (indentation, comments)
    WIP: Work In Progress not ready for merge

87 88 89 90 91 92 93 94 95 96
For example, here are some good commit messages:

    BUG: #1701 Warn users if parameter string is unset
    DOC: Fix typo in Monteverdi French translation
    COMP: Allow GeoTIFF and TIFF to be disabled when no 3rd party drags them

### Merge request

Your contribution is ready to be added to the main OTB repository? Send a Merge
Request against the `develop` branch on GitLab using the merge request
Victor Poughon's avatar
Victor Poughon committed
97 98
template. The merge request will then be discussed by the community and the core
OTB team.
99

100
* Merge requests can not be merged until all discussions have been resolved (this is enforced by GitLab)
Julien Michel's avatar
Julien Michel committed
101
* Merge requests **must receive at least 2 positives votes from core developers** (members of Main Repositories group in Gitlab with at least "Developer" level; this includes PSC members) before being merged
102
* The merger is responsible for checking that the branch is up-to-date with develop
103
* Merge requests can be merged by anyone (not just PSC or RM) with push access to develop
104 105
* Merge requests can be merged once the CI pipeline passes successfully. See
  next section for details on the CI pipelines.
106 107


108
### Using the CI platform
109

110 111
The CI pipelines are triggered automatically when pushing commits. If you push
to a fork, you will need a few settings to trigger properly the CI pipelines:
112

113 114 115 116
* You must add Runners for your fork: the best way is to ask access to the
  runners from main repository when doing your first MR. During code review,
  someone from CI admins will assign the runners to your fork.
* [Optional] You can create a
117 118 119 120 121
  [personal access token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html)
  (choose the scope API) and add it as a secret variable: on the project page of
  your fork, go to Settings -> CI/CD -> Variables, add the variable `K8S_SECRET_API_TOKEN`
  with your token as value (you should mask this variable for security reasons).

122
When your pipeline ends, there are two cases:
123 124 125 126 127 128 129 130 131

* if all the jobs succeed, you see a green pipeline, which means no problem was
  found on your commit.
* if one job fails, you see a red pipeline, which means something is broken in
  your commit. The pipeline widget on Gitlab will tell you which job failed. You
  will also find special jobs "cdash:..." in the stage `external` that provide
  a link to the [Dashboard](https://cdash.orfeo-toolbox.org/index.php?project=OTB)
  where you can look more in details into compilation errors and failed tests.

132 133
More details on the CI platform can be found
[here](https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/wikis/OTB-Continuous-Integration-platform).
134

135 136 137 138 139 140 141 142
### Contribution license agreement

OTB requires that contributors sign out a [Contributor License
Agreement](https://en.wikipedia.org/wiki/Contributor_License_Agreement). The
purpose of this CLA is to ensure that the project has the necessary ownership or
grants of rights over all contributions to allow them to distribute under the
chosen license (Apache License Version 2.0)

Julien Michel's avatar
Julien Michel committed
143
To accept your contribution, we need you to complete, sign and email to *cla [at]
144 145 146 147 148 149 150
orfeo-toolbox [dot] org* an [Individual Contributor Licensing
Agreement](https://www.orfeo-toolbox.org/cla/icla-en.doc) (ICLA) form and a
[Corporate Contributor Licensing
Agreement](https://www.orfeo-toolbox.org/cla/ccla-en.doc) (CCLA) form if you are
contributing on behalf of your company or another entity which retains copyright
for your contribution.

151 152 153 154
The copyright owner (or owner's agent) must be mentioned in headers of all
modified source files and also added to the [NOTICE
file](https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/raw/develop/NOTICE).

155 156
## Remote modules

157
[Remote Modules](https://wiki.orfeo-toolbox.org/index.php/Remote_Modules) are
158
the preferred way if you wish to make your apps and filters available to the
159 160 161 162 163
community while keeping control and maintenance of their sources. Remote
modules are just like regular modules, except they are not distributed inside
OTB source code. Under some conditions (dependencies, official acceptance
process, etc.), we are also able to distribute your remote module in the
official standalone binaries. See [the wiki](https://wiki.orfeo-toolbox.org/index.php/Remote_Modules)
164
for more information.
165

166
## GitLab guidelines
167

168
In order to organize the issues in our GitLab instance, we use both labels and
169 170 171
milestones.

The [milestones](https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/milestones) should be used to track in which release a feature is merged.
172
GitLab can then provide a summary of all features and bugs added to a given release
173 174 175 176 177 178 179
version.

Regarding labels, we use the following set:
* ~story: significant feature to be implemented with a detailed work plan, it can
  correspond to a Request for Comments that has turned into a development action
* ~bug: Bug, crash or unexpected behavior, reported by a user or a developer
* ~feature: Feature request expressed by an OTB user/developer
180
* ~patch: A small patch fixing build warnings, compilation errors, typos in logs or documentation
181 182 183
* ~"To Do": action is planned
* ~Doing: work in progress
* ~api ~app ~documentation ~monteverdi ~packaging ~qgis: optional context information
184 185 186 187 188 189 190 191 192 193 194 195 196

## Versioning

Starting from OTB 7.0.0, we use [semantic versioning](https://semver.org/). See the website for the full spec, in summary:

> Given a version number MAJOR.MINOR.PATCH, increment the:
>
>  1. MAJOR version when you make incompatible API changes,
>  2. MINOR version when you add functionality in a backwards-compatible manner, and
>  3. PATCH version when you make backwards-compatible bug fixes.
>
> Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

197
The develop branch is always the place where the upcoming major or minor release is worked on. Patch releases are done on release branches, for example 7.0.1 and 7.0.2 could be found on the release-7.0 branch.
198

199
For the purpose of defining backwards compatibility, the OTB API covers (not an exhaustive list): the C++ API, the Python bindings, application names, application parameters, output format and interpretation of input data.
200 201

When we deprecate part of our public API, we should do two things: (1) update our documentation to let users know about the change, (2) issue a new minor or major release with the deprecation in place.