contributing.md 15.3 KB
Newer Older
Luc Maisonobe's avatar
Luc Maisonobe committed
1
<!--- Copyright 2002-2022 CS GROUP
2
3
4
  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at
Sébastien Dinot's avatar
Sébastien Dinot committed
5

6
    http://www.apache.org/licenses/LICENSE-2.0
Sébastien Dinot's avatar
Sébastien Dinot committed
7

8
9
10
11
12
13
14
  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->

15
# Contributing to Orekit
16
17
18
19
20

Orekit is free software, which means you can use the source code as you wish,
without charges, in your applications, and that you can improve it and have
your improvements included in the next mainstream release.

Sébastien Dinot's avatar
Sébastien Dinot committed
21
22
23
24
25
26
Considering contributing? **Great! A warm thank you to you!** We are always
happy to have new contributors join our community and help us improve Orekit.
This document is intended to help you take your first steps in the project.

You can contribute in many ways:

27
* [Participate in the discussions on the forum](#participate)
Sébastien Dinot's avatar
Sébastien Dinot committed
28
29
30
31
* [Report bugs or feature requests](#report-bugs)
* [Improve the documentation](#improve-documentation)
* [Improve or extend the source code](#improve-source-code)

32
<span id="participate">**Participate in the discussions on the forum**</span>
Sébastien Dinot's avatar
Sébastien Dinot committed
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

You can participate in discussions on the [forum](https://forum.orekit.org/),
share your experience with Orekit or in space flight dynamics, provide help to
less experienced users, or simply explain the features you miss in Orekit.

We want everyone to have a good experience from their interactions with the
Orekit community. Please be welcoming, cordial and caring. Avoid insulting or
derogatory language, or other conduct which could reasonably be considered
inappropriate in a professional setting.

<span id="report-bugs">**Report bugs or feature requests**</span>

You can report bugs in our
[bug tracking system](https://gitlab.orekit.org/orekit/orekit/-/issues). If
you have trouble qualifying the problem, talk about it on the
[forum](https://forum.orekit.org/) first. **And remember: the more information
49
the community get, the easier the community can reproduce and fix it.**
Sébastien Dinot's avatar
Sébastien Dinot committed
50
51

The bug tracking system is also the right place to report your feature
52
53
54
55
56
requests. We do not promise to take them into account, and even less to do it
quickly, because we have limited human resources and our own priorities. But
by expressing your needs in the tracking system, you leave a record of them
and a contributor will be able to implement the feature when he or she will be
available.
Sébastien Dinot's avatar
Sébastien Dinot committed
57
58
59
60

<span id="improve-documentation">**Improve the documentation**</span>

You can help us improving the [existing documentation](index.html) or you can
61
62
write a new [tutorial](https://www.orekit.org/doc-tutorials.html), to help
users to better understand the use of some features.
Sébastien Dinot's avatar
Sébastien Dinot committed
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

Except for the tutorials, all the documentation is embedded with the source
code. You can find it in the
[src/site](https://gitlab.orekit.org/orekit/orekit/-/tree/develop/src/site)
directory of the Orekit source code repository. This documentation uses the
Markdown lightweight text format. It is integrated with the source code to
ensure its consistency with the source code version. Therefore, to contribute
to the documentation, you should proceed as if you were contributing to the
source code (see next point), but without having to write tests. ;)

If you want to enhance a tutorial or write a new one, please note that these
are managed in a dedicated project named
[Orekit tutorials](https://gitlab.orekit.org/orekit/orekit-tutorials),
available on our Gitlab forge. We invite you to read the
[specific contributing guide](https://www.orekit.org/site-orekit-tutorials-development/contributing.html)
for these tutorials.

<span id="improve-source-code">**Improve or extend the source code**</span>

You can provide us with a patch fixing a bug, improving an existing function
or implementing a new one.

If your contribution is minor and does neither affect the API nor the
architecture of Orekit, get started right away, following the recommendations
below in this guide. In all other cases, start by presenting the contribution
you plan to make on the [forum](https://forum.orekit.org/). The core team will
be able to analyze your proposal and confirm that it is compatible with the
objective and scope of the project, as well as with in progress and planned
developments. It will also prevent you from starting work that others are
already doing. This dialogue contributes to the smooth running of the project.
Even the core team members go through this exercise before launching into
a major contribution.

As Orekit is used for operational purposes, we want its source code to be
efficient, reliable, robust and easy to maintain. The code quality is even
a priority for us. We therefore strongly encourage you to read our
[development guidelines](https://www.orekit.org/site-orekit-development/guidelines.html).

We use a set of tools (CheckStyle, SpotBugs, SonarQube...) that check
compliance with our coding rules and perform static analysis of the source
code. This verification is carried out by the continuous integration process.
The [code quality report](https://sonar.orekit.org/dashboard?id=orekit%3Aorekit)
is established by SonarQube. Since using CheckStyle in Eclipse and configuring
SonarQube to take your project into account is not trivial, you will find
detailed instructions about them in this guide. We know that these "details"
may seem boring, but the quality of the source code determines the difficulty
109
110
the community will have in maintaining it. Therefore code quality is checked
before accepting contributions.
Sébastien Dinot's avatar
Sébastien Dinot committed
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

Are you ready to go? Great!

Here's how to make your first contribution:

1. Connect to the [Orekit forge](https://gitlab.orekit.org/users/sign_in). By
   default, to limit spam, you can only authenticate using your account on any
   of the Github, Gitlab.com or BitBucket platforms. If this bothers you,
   please [let us know](mailto:contact@orekit.org) and we will create a local
   account for you.

2. Create your own copy of the repository (i.e. "Fork the repository") on our
   forge by clicking on the "Fork" button at the top right of the Orekit
   repository. This is the red rectangle on the following image:

     ![fork](./images/orekit-fork.png)

3. Clone **your** repository on your workstation and checkout the **develop**
   branch.
Bryan Cazabonne's avatar
Bryan Cazabonne committed
130

131
132
133
134
135
136
4. Within your checked out repository, configure your username and email address so your contributions can be properly submitted:
    ```
    git config user.name "First Last"
    git config user.email "address@domain.tld"
    ```  
   
137
138
139
140
141
142
143
144
145
146
147
148
5. Create a new branch on your fork.

   The branch must have a name related to the future contribution.  
   For instance, if you want to correct an issue, the name must be **issue-XXX** where **XXX** represents the issue number.

   If you are contributing a new feature or are correcting a bug that will need an API change, have the **develop** branch as the source branch.  
   Your contribution will be eligible for a minor version or major version (if API is changed).
   
   **Important note:**  
   If you are correcting a bug with no API change needed, have the latest **release-X.Y** branch as the source branch.  
   Your contribution will be eligible for a patch version.  
   Patch versions are released more often and it really simplifies the work of the release manager if you start from the latest release branch.
Sébastien Dinot's avatar
Sébastien Dinot committed
149

150
6. Be sure to activate checkstyle (use the **checkstyle.xml** file at the root
151
152
    of the project) to help you follow the coding rules of Orekit (see
    examples below).
Sébastien Dinot's avatar
Sébastien Dinot committed
153

154
7. Perform your development and validation.
Sébastien Dinot's avatar
Sébastien Dinot committed
155

156
8. Update the **changes.xml** file in *src/changes/* directory (see former
157
158
159
160
161
    entries to help you).  
   *Note*: do this only if your work is planned for a minor/major version.  
   If your contribution can be added to a patch version, then the release manager will update the changes.xml file.  
   This file is a big source of merge conflicts so it's much easier to handle it in a go when doing the release.  
   See point 5 for the differences between minor/major versions and patch versions.
Sébastien Dinot's avatar
Sébastien Dinot committed
162

163
9. Run all Orekit tests to ensure everything works.
Sébastien Dinot's avatar
Sébastien Dinot committed
164

165
10. Commit your code on your branch and push it to Gitlab (you can make several
Sébastien Dinot's avatar
Sébastien Dinot committed
166
    local commits and push them at once).
Bryan Cazabonne's avatar
Bryan Cazabonne committed
167

168
11. Submit a merge request (a "MR" in the Gitlab jargon) on the forge, by
Sébastien Dinot's avatar
Sébastien Dinot committed
169
    clicking on the *New merge request* button:
Bryan Cazabonne's avatar
Bryan Cazabonne committed
170

Sébastien Dinot's avatar
Sébastien Dinot committed
171
172
173
174
175
176
177
    ![merge requests](./images/merge-requests.png)

    Gitlab will ask you for the source repository and branch (select your fork
    and working branch) and the target repository and branch (select Orekit
    official repository an the **develop** branch). Be sure that the target of
    your request is the **develop** branch of the official repository.

178
12. Gitlab notifies the core team members of your merge request. One of them
179
180
181
182
183
    will review it as soon as he or she can. If your contribution seems to
    meet the project's expectations, he or she will accept it. If not, he or
    she will explain to you how it could be improved. You can then enhance
    your contribution and push new commits, which will be automatically added
    to the current merge request.
Sébastien Dinot's avatar
Sébastien Dinot committed
184
185
186
187
188

If you have any question during your contribution you can also visit the forum
and ask them. The larger the community is, the better Orekit will be. The main
rule is that everything intended to be included in Orekit core must be
distributed under the Apache License Version 2.0.
189
190
191

## Configure Orekit checkstyle

192
193
194
195
Checkstyle is a development tool to help programmers write Java code that is
compliant with a coding standard. It automates the process of checking Java
code to spare humans of this boring (but important) task. This makes it ideal
for projects that want to enforce a coding standard.
196

197
198
199
200
201
202
203
204
205
206
### Verify checkstyle using Maven

Checkstyle violations can be quickly verified in a Linux terminal by using
Maven commands. Contributors can execute the following command in the same
folder as the `pom.xml` file:

    mvn checkstyle:check findbugs:check test

Note that this command is also used to check that no Spotbugs warning were
created (`findbugs:check`) and that the tests are running correctly (`test`).
207
208
209

### Configure checkstyle in Eclipse

210
211
212
Configuring checkstyle can be a difficult task when installing Orekit in an
Integrated Development Environment (IDE). However, it is an important step for
contributing to the library.
Sébastien Dinot's avatar
Sébastien Dinot committed
213
Here are the steps you will need to follow to configure checkstyle in Eclipse.
214

Sébastien Dinot's avatar
Sébastien Dinot committed
215
#### Installing Eclipse Checkstyle plugin.
216

Sébastien Dinot's avatar
Sébastien Dinot committed
217
In your Eclipse IDE, select *Help* -> *Install New Software...*
218

Sébastien Dinot's avatar
Sébastien Dinot committed
219
220
Pressing the *Add...* button at the top right of the install wizard will
display a small popup asking for the name and location of a new software site.
221
222

* Name = Checkstyle
223
* Location = https://checkstyle.org/eclipse-cs-update-site
224
225
226

Press *Add* to close the popup.

Sébastien Dinot's avatar
Sébastien Dinot committed
227
228
Select *Checkstyle* in the *Install* window and click on *Next >*. Proceed to
the end of the wizard, accepting the licenses of the plugin and installing it.
229

Sébastien Dinot's avatar
Sébastien Dinot committed
230
#### Configuring the project.
231

Sébastien Dinot's avatar
Sébastien Dinot committed
232
233
To create the local configuration, select *Properties* by right-clicking in
the context menu of the project explorer panel.
234
235
236

In the *Properties* popup, select *Checkstyle* entry.

Sébastien Dinot's avatar
Sébastien Dinot committed
237
In this second popup (i.e. *Local Check Configurations*) define a project
238
239
relative configuration as presented in the figure below. Browse the workspace
to select your checkstyle.xml file, and tick the *Protect Checkstyle
240
configuration file* check box to prevent the plugin from altering the
Sébastien Dinot's avatar
Sébastien Dinot committed
241
configuration.
242
243
244

![checkstyle-plugin](./images/project-checkstyle-configuration.png).

Sébastien Dinot's avatar
Sébastien Dinot committed
245
246
247
The property must be defined by pressing the *Additional properties...*
button, which will trigger yet another popup into which the property can be
configured as shown below.
248
249
250

![additional-properties](./images/additional-properties.png)

Sébastien Dinot's avatar
Sébastien Dinot committed
251
252
253
Pressing the OK button in the last open popup ends the local check
configuration creation. Select the *Main* tab in the first popup, which should
still be opened.
254

Sébastien Dinot's avatar
Sébastien Dinot committed
255
256
257
258
259
260
261
In the *Main* tab, un-tick the *Use simple configuration* checkbox at the top
right. A few buttons should appear, allowing to remove the default Sun checks
global configuration (selecting it and pressing the *Remove* button) and add
our local configuration instead (pressing the *Add...* button). Using for
example **src/main/java/.*\.java** will apply checkstyle only to the files in
the **src/main/java** directory and not to the files in the **src/test/java**
directory.
262
263
264
265
266

![main-checkstyle-configuration](./images/main-checkstyle-configuration.png)

Press *OK* and *Apply and Close* to finish the installation.

Sébastien Dinot's avatar
Sébastien Dinot committed
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
#### Activate the checkstyle

Select *Checkstyle* -> *Activate Checkstyle* by right-clicking in the context
menu of the project explorer panel.

## Configure SonarQube

In order for SonarQube to check the quality of your source code, you must
initialize the project in SonarQube. Here is how to do it.

1. Connect to [our SonarQube instance](https://sonar.orekit.org/) using your
   Gitlab account.

2. The first time you log in, SonarQube will prompt you to generate a token.
   Generate it and keep it safe on your workstation. If you did not do so the
   first time you logged in, you can do so later by going to your account
   settings on SonarQube: *My account* -> *Security* -> *Generate Tokens*.

3. Then connect to Gitlab.

4. Go to the continuous integration (CI) configuration page of your fork
   (*Settings* -> *CI/CD* -> *Variables* -> *Expand*) and declare a variable
   named `SONAR_TOKEN`. The value of this variable must be the value of the
   token provided by SonarQube. Check the *Mask variable* option and click on
   *Add variable*.

5. SonarQube dynamically initiates the project on the first submission, but
   this first submission must be on the **master** branch. You can cause this
   by manually triggering a pipeline. Starting with Orekit version 11, you
   just need to go to the pipelines page (*Project homepage* -> *CI/CD* ->
   *Pipelines*), then click on *Run pipeline*, then select the **master**
   branch, then click on the *Run pipeline* button. Then wait for half an
   hour, which is approximately the time needed to compile and run the tests.

6. After that, you can run again the pipeline on your working branch.

303
304
305
306
307
If your working branch is from an Orekit version prior to 11.0, step 5
described above will not work because of the continuous integration scripts
did not manage forks properly. In this case, you will need to initiate the
project in SonarQube from your workstation, by executing the following
commands:
Sébastien Dinot's avatar
Sébastien Dinot committed
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323

```bash
$ cd orekit-repository
$ git switch master

$ export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64

$ mvn -s .CI/maven-settings.xml --batch-mode --errors --fail-at-end \
      --show-version -DinstallAtEnd=true -DdeployAtEnd=true verify site

$ export SONAR_TOKEN=<your-sonarqube-token>
$ export CI_PROJECT_TITLE=Orekit
$ export CI_PROJECT_NAMESPACE=<your-namespace>
$ export CI_PROJECT_NAME=orekit
$ export SONAR_PROJECT_KEY="${CI_PROJECT_NAMESPACE}:${CI_PROJECT_NAME}"
$ export SONAR_PROJECT_NAME="${CI_PROJECT_TITLE} (${CI_PROJECT_NAMESPACE}:${CI_PROJECT_NAME})"
324

Sébastien Dinot's avatar
Sébastien Dinot committed
325
326
327
328
329
$ mvn -s .CI/maven-settings.xml --batch-mode --errors --fail-at-end \
      --show-version -DinstallAtEnd=true -DdeployAtEnd=true sonar:sonar \
      -Dsonar.login=$SONAR_TOKEN -Dsonar.projectKey="$SONAR_PROJECT_KEY" \
      -Dsonar.projectName="$SONAR_PROJECT_NAME"
```