release-guide.md 21.2 KB
Newer Older
1
2
3
4
# Orekit Release Guide

This release guide is largely inspired from [Hipparchus Release
Guide](https://www.hipparchus.org/release-guide.html). It lists the steps that
5
6
have been used in the past to release a new version of Orekit.  
When in doubt, ask a question on the ["Orekit development" section of the forum](https://forum.orekit.org/c/orekit-development/5).
7

8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

Three types of versions can be released:
 - **Major version**: numbered xx.0, a version that can introduce both new features and bug corrections.  
 This is the only type of version where APIs are allowed to evolve, creating eventual incompatibilities with former versions.
 - **Minor version**: numbered xx.y, a version that can introduce both new features and bug corrections but where breaking APIs is forbidden.  
 A version xx.y must be perfectly compatible with its xx.0 major version counterpart.
 - **Patch version**: numbered xx.y.z, a version where only bug corrections are allowed.  
 Once again APIs incompatibility with version xx.y or xx.0 are not allowed.  
 A patch version is the only type of version where a vote from the PMC isn't required to publish the release.


Since there are some differences in the releasing process between minor/major versions and patch versions, this guide is split in two distinct sections.  
The first one deals with releasing a major/minor version, while the second one is dedicated to patch versions and is mainly a list of differences between the two releasing processes.

# Releasing a Major / Minor version

## 0. Prerequisites

### SonaType OSS Account
27
28
29
30
31
32
33
34
35

1. Obtain private key of the Orekit Signing Key, key id:
   `0802AB8C87B0B1AEC1C1C5871550FDBD6375C33B`
2. Register for account on OSSRH and associate it with the Orekit project, see:
   https://central.sonatype.org/pages/ossrh-guide.html

If you need help with either ask on the development section of the Orekit
forum.

Luc Maisonobe's avatar
Luc Maisonobe committed
36
Once you have a SonaType OSS account, the corresponding credentials must be set
37
38
39
40
41
42
43
44
45
46
47
48
49
in the `servers` section of the `$HOME/.m2/settings.xml` file, using an id of
`ossrh`:

    <servers>
      <server>
        <id>ossrh</id>
        <username>the user name to connect to the OSS site</username>
        <password>the encrypted password</password>
      </server>
    </servers>

Use `mvn -ep` to generate an encrypted password.

50
### Install Graphviz 2.38
51

52
Graphviz is used to produce the UML diagrams for the site (see /src/design/*.puml files).  
53
54
55
56
Graphviz (dot) 2.39 and above put too much blank space in the generated
diagrams. The bug has not yet been fixed in graphviz, so we have to use 2.38 or
earlier. The version in CentOS 7 works, the version in Ubuntu 18.04 does not.

57
## 1. Verify the status of develop branch
58
59

Before anything, check on the [continuous integration
60
site](https://sonar.orekit.org/dashboard?id=orekit%3Aorekit) that everything is fine on
61
62
63
develop branch:

* All tests pass;
64
65
* Code coverage is up to the requirements;
* There are no bugs, vulnerabilities or code smells.
66
67
68

If not, fix the warnings and errors first!

69
70
71
It is also necessary to check on the [Gitlab CI/CD](https://gitlab.orekit.org/orekit/orekit/pipelines)
that everything is fine on develop branch (i.e. all stages are passed).

72
## 2. Prepare Git branch for release
73
74
75
76
77
78
79
80

Release will be performed on a dedicated branch, not directly on master or
develop branch. So a new branch must be created as follows and used for
everything else:

    git branch release-X.Y
    git checkout release-X.Y

81
## 3. Update Maven plugins versions
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
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

Release is a good opportunity to update the maven plugin versions. They are all
gathered at one place, in a set of properties in `orekit/pom.xml`:

    <!-- Project specific plugin versions -->
    <orekit.spotbugs-maven-plugin.version>3.1.11</orekit.spotbugs-maven-plugin.version>
    <orekit.jacoco-maven-plugin.version>0.8.3</orekit.jacoco-maven-plugin.version>
    <orekit.maven-assembly-plugin.version>3.1.1</orekit.maven-assembly-plugin.version>
    ...

You can find the latest version of the plugins using the search feature at
[http://search.maven.org/#search](http://search.maven.org/#search). The
properties name all follow the pattern `orekit.some-plugin-name.version`, the
plugin name should be used in the web form to check for available versions.

Beware that in some cases, the latest version cannot be used due to
incompatibilities. For example when a plugin was not recently updated and
conflicts appear with newer versions of its dependencies.

Beware also that some plugins use configuration files that may need update too.
This is typically the case with `maven-checkstyle-plugin` and
`spotbugs-maven-plugin`. The `/checkstyle.xml` and
`/spotbugs-exclude-filter.xml` files may need to be checked.

Before committing these changes, you have to check that everything works. So
run the following command:

    mvn clean
    LANG=C mvn -Prelease site

If something goes wrong, either fix it by changing the plugin configuration or
roll back to an earlier version of the plugin.

Browse the generated site starting at page `target/site/index.html` and check
that everything is rendered properly.

When everything runs fine and the generated site is OK, then you can commit the
changes:

    git add orekit/pom.xml orekit/checkstyle.xml orekit/spotbugs-exclude-filter.xml
    git commit -m "Updated maven plugins versions."

124
## 4. Updating changes.xml
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

Finalize the file `/src/changes/changes.xml` file.

The release date and description, which are often only set to `TBD` during
development, must be set to appropriate values. The release date at this step
is only a guess one or two weeks in the future, in order to take into account
the 5 days release vote delay.

Replace the `TBD` description with a text describing the version released:
state if it is a minor or major version, list the major features introduced by
the version etc. (see examples in descriptions of former versions).

Commit the `changes.xml` file.

    git add src/changes/changes.xml
    git commit -m "Updated changes.xml for official release."

142
## 5. Updating documentation
143
144
145

Several files must be updated to take into account the new version:

Guilhem Bonnefille's avatar
Guilhem Bonnefille committed
146
147
148
149
150
151
|            file name                |           usage            |                                     required update                                                    |
|-------------------------------------|----------------------------|--------------------------------------------------------------------------------------------------------|
| `build.xml`                         | building file for Ant users| Update project version number. Check all dependencies' versions are consistent with pom.xml            |
| `src/site/markdown/index.md`        | site home page             | Update the text about the latest available version, including important changes from **changes.xml**   |
| `src/site/markdown/downloads.md.vm` | downloads links            | Declare the new versions, don't forget the date                                                        |
| `src/site/markdown/faq.md`          | FAQ                        | Add line to the table of dependencies.                                                                 |
152
153
154
155
156
157
158
159

Make sure the ant build works: `ant clean clean-lib jar javadoc`.

Once the files have been updated, commit the changes:

    git add build.xml src/site/markdown/*.md
    git commit -m "Updated documentation for the release."

160
## 6. Change library version number
161
162
163
164
165
166
167
168
169
170

The `pom.xml` file contains the version number of the library. During
development, this version number has the form `X.Y-SNAPSHOT`. For release, the
`-SNAPSHOT` part must be removed.

Commit the change:

    git add pom.xml
    git commit -m "Dropped -SNAPSHOT in version number for official release."

171
## 7. Check the JavaDoc
172
173
174
175
176
177
178
179

Depending the JDK version (Oracle, OpenJDK, etc), some JavaDoc warnings can be present.
Make sure there is no JavaDoc warnings by running the following command:

    mvn javadoc:javadoc

If possible, run the above command with different JDK versions.

180
181
182
183
184
185
186
187
188
189
190
## 8. Build the site

The site is generated locally using:

    mvn clean
    LANG=C mvn site

The official site is automatically updated on the hosting platform when work is 
merged into branches `develop`, `release-*` or `master`.

## 9. Tag and sign the git repository
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205

When all previous steps have been performed, the local git repository holds the
final state of the sources and build files for the release. It must be tagged
and the tag must be signed. Note that before the vote is finished, the tag can
only signed with a `-RCx` suffix to denote Release Candidate. The final tag
without the `-RCx` suffix will be put once the vote succeeds, on the same
commit (which will therefore have two tags). Tagging and signing is done using
the following command, with `-RCn` replaced with the Release Candidate number:

    git tag X.Y-RCn -s -u 0802AB8C87B0B1AEC1C1C5871550FDBD6375C33B -m "Release Candidate n for version X.Y."

The tag should be verified using command:

    git tag -v X.Y-RCn

206
## 10. Pushing the branch and the tag
207
208
209
210
211
212

When the tag is ready, the branch and the tag must be pushed to Gitlab so
everyone can review it:

    git push --tags origin release-X.Y

213
*Good practice*: wait for the CI to succeed on the branch then release-X.Y branch on [SonarQube](https://sonar.orekit.org/dashboard?id=orekit%3Aorekit) and check that everything is fine
214

215
## 11. Generating signed artifacts
216
217
218
219

When these settings have been set up, generating the artifacts is done by
running the following commands:

220
    mvn deploy -DskipStagingRepositoryClose=true -Prelease
221
222
223
224
225
226
227
228
229
230
231
232
233
234

During the generation, maven will trigger gpg which will ask the user for the
pass phrase to access the signing key. Maven didn’t prompt for me, so I had to
add `-Dgpg.passphrase=[passphrase]`

Once the commands ends, log into the SonaType OSS site
[https://oss.sonatype.org/](https://oss.sonatype.org/) and check the staging
repository contains the expected artifacts with associated signatures and
checksums:

- orekit-X.Y.pom
- orekit-X.Y.jar
- orekit-X.Y-sources.jar
- orekit-X.Y-javadoc.jar
Luc Maisonobe's avatar
Luc Maisonobe committed
235
236
237
238
239
240
241
242

The signature and checksum files have similar names with added extensions `.asc`,
`.md5` and `.sha1`.

Sometimes, the deployment to Sonatype OSS site also adds files with double extension
`.asc.md5` and `.asc.sha1`, which are in fact checksum files on a signature file
and serve no purpose and can be deleted.

243
244
Remove `orekit-X.Y.source-jar*` since they are duplicates of the
`orekit-X.Y-sources.jar*` artifacts. (We can’t figure out how to make maven
245
stop producing these duplicate artifacts). **Then click the “Close” button.**
246

247
## 12. Calling for the vote
248
249

Everything is now ready so the developers and PMC can vote for the release.
Luc Maisonobe's avatar
Luc Maisonobe committed
250
251
Create a post in the Orekit development category of the forum with a subject
line of the form:
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270

    [VOTE] Releasing Orekit X.Y from release candidate n

and content of the form:

    This is a VOTE in order to release version X.Y of the Orekit library.
    Version X.Y is a maintenance release.


    Highlights in the X.Y release are:
      - feature 1 description
      ...
      - feature n description

    The release candidate n can be found on the GitLab repository as
    tag X.Y-RCn in the release-X.Y branch:
    <https://gitlab.orekit.org/orekit/orekit/tree/X.Y-RCn>

    The release notes can be read here:
271
    <https://test.orekit.org/site-orekit-X.Y/changes-report.html>
272
273
274
275
276
277
278

    Maven artifacts are available at
    <https://oss.sonatype.org/content/repositories/orgorekit-xxxx/>.

    The votes will be tallied in 120 hours for now, on 20yy-mm-ddThh:mm:00Z
    (this is UTC time).

Luc Maisonobe's avatar
Luc Maisonobe committed
279
280
281
You should also ping PMC members so they are aware of the vote. Their
vote is essential for a release as per project governance.

282
### 12.1. Failed vote
283
284
285
286
287
288
289
290

If the vote fails, the maven artifacts must be removed from OSS site by
dropping the repository and non-maven artifacts must be removed from the
`staging` directory in the Orekit site. Then a new release candidate must
be created, with a new number, a new tag and new artifacts. Another vote is
needed for this new release candidate. So make the necessary changes and then
start from the “Tag and sign the git repository” step.

291
### 12.2. Successful vote
292
293
294
295

When the vote for a release candidate succeeds, follow the steps below to
publish the release.

296
## 13. Tag release version
297
298
299
300
301
302
303
304

As the vote passed, a final signed tag must be added to the succeeding release
candidate, verified and pushed:

    git tag X.Y -s -u 0802AB8C87B0B1AEC1C1C5871550FDBD6375C33B -m "Version X.Y."
    git tag -v X.Y
    git push --tags

305
## 14. Merge release branch into master
306

307
Merge the release branch into the `master` branch to include any changes made.
308

309
    git checkout master
310
311
    git merge --no-ff release-X.Y

312
Then commit and push.
313

314
315
316
*Good practice*: Again, wait for the CI to succeed and check on SonarQube that the master branch report is fine.

## 15. Merge master branch into develop
317

318
Merge the `master` branch into the `develop` branch to include any changes made.
319

320
321
    git checkout develop
    git merge --no-ff master
322

323
324
Then updated the version numbers to prepare for the next development cycle.
Edit pom.xml version to SNAPSHOT and make space in the `/src/changes/changes.xml`
325
326
327
file for new changes.

Then commit and push.
328

329
330
331
*Good practice*: Again, wait for the CI to succeed and check on SonarQube that the develop branch report is fine.

## 16. Publish maven artifacts
332

333
The maven artifacts must be published using OSS site to release the repository.
334
Select the Orekit repository in “Staging Repositories” and click the “Release”
335
button in [Nexus Repository Manager](https://oss.sonatype.org/).
336

337
## 17. Upload to Gitlab
338

339
Navigate to Projects > Orekit > Deployments > Releases and make sure the X.Y release notes looks nice.
340

341
## 18. Synchronize the Github mirror
342

343
344
345
346
To enhance the visibility of the project,
[a mirror](https://github.com/CS-SI/Orekit) is maintained on Github. The
releases created on Gitlab are not automatically pushed on this mirror. They
have to be declared manually to make visible the vitality of Orekit.
347
348
349
350

1. Login to Github
2. Go to the [Orekit releases](https://github.com/CS-SI/Orekit/releases) page
3. Click on the [Draft a new release](https://github.com/CS-SI/Orekit/releases) button
351
352
4. In the “Tag version” field of the form and in the “Release title” field,
   enter the tag of the release to be declared
353
5. Describe the release as it has been done on Gitlab
354
6. Click on “Publish release”
355
356
357

Github automically adds two assets (zip and tarball archives of the tagged source code)

358
359
360
## 19. Update Orekit site

Several edits need to be done to the Orekit website after the vote.
361

362
First, clone the current code:
363

364
    git clone https://gitlab.orekit.org/orekit/website-2015
365

366
367
368
369
370
Switch to `develop` branch.
Edit `overview.html`:
 - (If needed) Update the new Hipparchus version.  
 - Update the `overview.png` image with the new version numbers.
 - (If needed) Update the *Features* section with the new features added by the new version of Orekit.
371

372
Create a new post for the release in `_post/`, it will be visible in the `News` page (see section *Announce Release* for the content of the post).
373

374
Push the modifications on `develop` branch, wait until the pipeline on Gitlab is finished, then the [test website](https://test.orekit.org/) will be updated.
375

376
377
Check that everything looks nice and then merge `develop` on `master` branch and push the modifications.  
When the Gitlab pipeline is finished, the [official website](https://orekit.org/) should be updated according to your changes.
378

379
## 20. Close X.Y milestone
380

381
382
In Gitlab, navigate to Projects > Orekit > Issues > Milestones.
Click “Close Milestone” for the line corresponding to the release X.Y.
383

384
## 21. Announce release
385

386
387
The last step is to announce the release by creating a post in the Orekit
announcements category of the forum with a subject line of the form:
388

389
390
391
392
    Orekit X.Y released

and content of the form:

393
394
395
    The Orekit team is pleased to announce the release of Orekit version X.Y.
    This is a minor/major version, including both new features and bug fixes.
    The main changes are:
396
397
398
399
400
401
402
403

      - feature 1 description
      ...
      - feature n description

    This version depends on Hipparchus X'.Y'

    For complete release notes please see:
404
    https://www.orekit.org/site-orekit-X.Y/changes-report.html
405

406
407
    The maven artifacts are available in maven central. 
    The source and binaries can be retrieved from the forge releases page:
408
    https://gitlab.orekit.org/orekit/orekit/-/releases
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536


# Releasing a Patch version

Here the main difference are that:
 - We're going to use a former release branch to do the release;
 - A vote of the PMC is not required to release the version.

If we're releasing patch version X.Y.Z, then we're going to use the already existing `release-X.Y` branch on the repository to do the release.  
With:
 - X: Major version number
 - Y: Minor version number
 - Z: Patch version number

 Once again, a patch version should only contain bug fixes that do not break APIs !

## 0. Prerequisites
Prerequisites are the same as for a minor/major version.

## 1.1 Verify the status of the already existing release branch

Here we will run the same checks than for a minor/major version but on the `release-X.Y` branch instead of the `develop` branch.  
See above for the checks (SonarQube: tests, code coverage, code quality / Gitlab CI/CD: all stages passed succesfully).

One could argue that the `release-X.Y` branch should always be in a clean state since it contains the latest release.  
However, for patches purpose, developers may have merged bug corrections on the `release-X.Y` branch since the last release.

## 1.2 Verify the status of the remaining opened merge requests

Here we are going to verify the status of each still-opened merge request (MR) that is in the scope of the version.  

Start from the [milestone](https://gitlab.orekit.org/orekit/orekit/-/milestones) of the version, note the issues in the scope that are not closed, and find the associated MR.  

Then, for each MR:
* Check that the pipeline was a success (i.e. all stages passed)
* If it exists, find the SonarQube report for the MR, either in a short-lived branch of [Orekit main CI report](https://sonar.orekit.org/dashboard?id=orekit%3Aorekit) or on the developer own [sub-project](https://sonar.orekit.org/projects?sort=-analysis_date) on SonarQube.  
Check that:
  * All tests pass;
  * Code coverage is up to the requirements;
  * There are no bugs, vulnerabilities or code smells.

If not, ask for a fix of the warnings and errors first!

## 2. Prepare Git branch for release

The patch release will be performed on previous release branch.

So first, check out the dedicated branch:

    git checkout release-X.Y

Then, merge all the merge requests (MR) in the scope of the version in branch release-X.Y.  

There are two cases here, they are detailed in the two points below.

### 2.1. Merging the remaining merge requests

If the developer made his changes starting from branch `release-X.Y`, you can simply merge the branch of the MR in branch `release-X.Y`.

Note that if there aren't any conflict in Gitlab you can directly do the merge from Gitlab; just make sure that the target branch is `release-X.Y` and not "develop".

Find the MR on the repository, it should be in branch `origin/merge-requests/XXX` with XXX the number of the MR  

    git merge --no-ff origin/merge-requests/XXX

The `--no-ff` option will force a merge commit to be made, instead of doing a fast-forward on the branch.  
You can keep the automatic merge message unless you want to add some content to it.

Eventually, resolve any conflict and commit the result.

### 2.2. Cherry-picking the commits

If the developer started from develop branch (or any other branch), then the MR branch may contain code that should not be added to the release.  
You will have to cherry-pick the appropriate commits and add them to a dedicated branch.  
It is advised to use an IDE to do the cherry-picking although the command lines below will help you.

Find the MR on the repository and the commits you are interested in.

Create a dedicated branch for the issue on your local repository:

    git checkout -b issue-YYY

Where YYY is the number of the issue that the MR XXX fixes.  
If the branch already exists, give it a different name like `integrate-issue-YYY` or `integrate-MR-XXX`

Make a list of the IDs of the commits you want to add, example `A B C D` (in the order they were committed).

Cherry-pick the commits in a chronological order:

    git cherry-pick A B C D

Eventually, resolve any conflict and commit the result.

Return to the release branch and merge the branch issue-YYY:

    git checkout release-X.Y
    git merge --no-ff issue-YYY

## 3. Update Maven plugins versions
**Skip this** for a patch version.

## 4. Update changes.xml
Do the same as for a minor/major version.
## 5. Updating documentation
Do the same as for a minor/major version.

## 6. Change library version number

The `pom.xml` file contains the version number of the library.  
On the release-X.Y branch, the version number should be `X.Y` or `X.Y.Z` if a patch was already released for this version.

Replace version number from `X.Y` to `X.Y.1` or `X.Y.Z` to `X.Y.Z+1`

Commit the change:

    git add pom.xml
    git commit -m "Increment version number for patch release."

## Steps 7 to 11
Do the same as for a minor/major version.

## 12. Calling for the vote
**Skip this** for a patch version.

As per Orekit governance rules, a vote of the PMC is not required for a patch version.

## Steps 13 to 21
Do the same as for a minor/major version.