CONTRIBUTING.md 14.4 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
21
22
Remember to check out also our [forum](https://forum.orfeo-toolbox.org/), 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!
23
24
25

## Reporting bugs

26
27
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)
28
29
to see if it has already been reported.

30
31
32
33
If it's a new bug, please [open a new issue on
GitLab](https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/issues/new).  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!
34
35
36

## Feature requests and discussions

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


## Documentation improvements

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

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

## Code contribution

55
56
The OTB workflow is based on GitLab [Merge
Requests](https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html).
57
58
59
60
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.

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

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

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

72
73
74
75
### 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
76
77
78
79
commit message so that GitLab can [cross-link
it](https://docs.gitlab.com/ce/user/project/issues/crosslinking_issues.html).
You can prefix your commit message with an indicating flag (DOC, BUG, PKG, TEST,
SuperBuild, etc.).
80

81
82
83
84
85
86
87
88
89
90
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

91
92
93
94
95
96
97
98
99
100
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
101
102
template. The merge request will then be discussed by the community and the core
OTB team.
103

104
105
106
107
108
109
110
111
112
* Merge requests can not be merged until all discussions have been resolved
  (this is enforced by GitLab)
* 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
* The merger is responsible for checking that the branch is up-to-date with
  develop
* Merge requests can be merged by anyone (not just PSC or RM) with push access
  to develop
113
114
* Merge requests can be merged once the CI pipeline passes successfully. See
  next section for details on the CI pipelines.
115
116


117
### Using the CI platform
118

119
120
There isn't much to do in order to use the CI platform. The CI pipelines are
triggered automatically when pushing commits. However, if you push to a fork,
121
122
123
you will first need an access to the Runners from main repository. You can
request it when doing your first Merge Request. During code review, someone from
CI admins will assign the runners to your fork.
124

125
When your pipeline ends, there are two cases:
126
127
128
129

* 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
130
  your commit. The pipeline widget on GitLab will tell you which job failed, so
131
132
133
  you can check the logs. There, you may also find links to
  [CDash](https://cdash.orfeo-toolbox.org/index.php?project=OTB) submissions
  where compilation errors and failed test can be investigated more easily.
134

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

138
139
140
141
142
143
144
145
### 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)

146
147
To accept your contribution, we need you to complete, sign and email to *cla
[at] orfeo-toolbox [dot] org* an [Individual Contributor Licensing
148
149
150
151
152
153
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.

154
155
156
157
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).

158
159
## Remote modules

160
161
162
163
164
Remote Modules are the preferred way if you wish to make your apps and filters
available to the community while keeping control and maintenance of their
sources. Those modules are just like regular modules, except they are not
distributed inside OTB source code. For more information, see [the
CookBook](https://www.orfeo-toolbox.org/CookBook-develop/RemoteModules.html)
165

166
## GitLab guidelines
167

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

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

Regarding labels, we use the following set:
176
177
178
179
180
181
182
183
184

| Label                                              | Description                                                                                                                                            |
|----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| ~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                                                                                                     |
| ~usage                                             | Question related to OTB's usage                                                                                                                        |
| ~patch                                             | A small patch fixing build warnings, compilation errors, typos in logs or documentation                                                                |
| ~"to investigate"                                  | This issue needs a complete analysis                                                                                                                   |
Yannick TANGUY's avatar
Yannick TANGUY committed
185
| ~"CNES backlog"                                    | The CNES could fund this issue but it has not been assigned to a milestone yet                                                                            |
186
187
188
189
190
| ~"To Do"                                           | Action is planned                                                                                                                                      |
| ~Doing                                             | Work in progress                                                                                                                                       |
| ~"Waiting for answer"                              | Waiting for an answer or for a detailed context                                                                                                        |
| ~breaking                                          | Changes introduced by this issue will break the API                                                                                                    |
| ~refactoring                                       | Issue related to improvements like refactoring, tests, maintenance, etc                                                                                |
Laurențiu Nicola's avatar
Laurențiu Nicola committed
191
192
| ~documentation                                     | Documentation improvements|
| ~ci                                                | Issue related to the continuous integration platform                                                                                                  |
193
194
| ~api ~app ~legal ~monteverdi <br> ~packaging ~qgis | Optional context information                                                                                                                           |
  
Laurențiu Nicola's avatar
Laurențiu Nicola committed
195
## Issue life cycle
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210

When an issue is open, the core development team will review it in a
first analysis. During this first analysis, the team will evaluate is
the issue is a ~bug, a ~feature request or related to an ~usage. The
team may also ask for more information.

### Bugs

Sometimes, the first analysis shows that the issue is related to a
misuse of the OTB. In that case, the issue is redefined to ~usage.

It happens that the bug is trivial to correct or a workaround is easy
to set up. In this case, it is corrected directly, or the workaround
is documented, and the issue is closed. If the bug is not trivial, the
team will proceed to a second, more complete, analysis. During this
Yannick TANGUY's avatar
Yannick TANGUY committed
211
analysis, the issue is marked as ~"to investigate". This is a time to
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
iterate with the author of the issue to find the best way to address
it. At the end of this analysis, the issue's description should
contain the proposition of correction, the impact for the code and the
test, the validation criterion, and an estimation of the
implementation schedule. Sometimes, a workaround can be proposed in
place of a correction.

As the main funder of the project, the CNES may support the funding
for the correction, but it is not systematic, since its funds are
limited. In case of CNES funding, the issue is assigned to a milestone
(the next minor release or the next major release).

### Feature request

The core development team will proceed to a second, more complete,
Yannick TANGUY's avatar
Yannick TANGUY committed
227
analysis. During this analysis, the issue is marked as ~"to
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
investigate". This is a time to iterate with the author of the issue
to find the best way to address it. At the end of this analysis, the
issue's description should contain the conception of the new feature,
the impact for the users, the code and the test, the validation
criterion, and an estimation of the implementation schedule. In case
of CNES funding, the issue is assigned to a milestone (the next minor
release or the next major release). If the request doesn't correspond
to the roadmap of those milestone, the label ~"CNES backlog" is set to
the issue.

### Usage

When someone asks a question about the usage of the OTB, or doesn't understand
some functionalities, the community will be pleased to help them by answering
the questions and providing some support. This kind of issues are also an
opportunity to improve the documentation and make the OTB easier to use.
244
245
246

## Versioning

247
248
Starting from OTB 7.0.0, we use [semantic versioning](https://semver.org/). See
the website for the full spec, in summary:
249
250
251
252
253
254
255
256
257

> 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.

258
259
260
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.
261

262
263
264
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.
Victor Poughon's avatar
Victor Poughon committed
265

266
267
268
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.