This guide contains the step-by-step process to complete an EPP release.
The individual releases are tracked with endgame issues on GitHub issues.
For each release (M1, M2, M3, RC1, RC2) an endgame ticket is created with the appropriate contents from the rest of this document:
[x] Check for bad links to Bugzilla (other things?) especially in epp.website.xml
[x] Make sure any outstanding reviews are progressing - e.g. file IP logs, get PMC approval, etc.
For 2022-03 there is no review planned, next review expected to be a progress review around 2022-06
[x] Ensure that the CI build is green. Resolving non-green builds will require tracking down problems and incompatibilities across all Eclipse participating projects. cross-project-issues-dev mailing list is a good place to start when tracking such problems.
[x] Check that packages containing incubating projects have that information reflected in Help -> About dialog. See near the end of build output for report of check-incubating.sh script.
-incubation and (includes Incubating components) are not used in packageMetaData anymore (See Bug 564214)
[ ] On RC1 check "new and noteworthy" version numbers - If any N&N are out of date, remove the N&N entries and notify the corresponding package maintainer.
[ ] Search for url= (notice the blank before url) in epp.website.xml to see which ones are contained in the different packages.
[ ] Remember that some of the features will release new versions together with the new Eclipse release. Therefore using the currently released version number may be wrong. Instead lookup the feature version to be released with the release train.
[x] Synchronize the following - Remember to check branch, these links are to master, but around RC2 master may be setup for next release already
[x] Synchronize any changes to platform.product into all the epp.product files.
[x] Synchronize any changes to platform.p2.inf into all the *.product/p2.inf files.
[x] Synchronize any changes to platform's icons' into icons root directory.
[x] Synchronize the list of contents in product file with the cooresponding p2.inf
One way to do this is gitk -- **/epp.product **/p2.inf and make sure every change to included features in epp.product has a matching change in p2.inf. You should only have to look as far back as the last M or RC build.
[x] Update name of the release in strings with a "smart" global find&replace. Be careful on M3 that the replace did not match the Eclipse project name M2E! See this gerrit for an example. Use commit message like [releng] Prepare repo for 2020-12 M1. In particular, check:
TODO can this be automated On M1 add the M1 qualifier (e.g. 2021-03-R -> 2021-06-M1, on RC2 set it to R the qualifier e.g. 2021-03-RC1 -> 2021-03-R). Except for eclipse.simultaneous.release.name which should go from 2021-03 (4.19.0) -> 2021-06 M1 (4.20.0 M1) on M1 and 2021-03 RC1 (4.19.0 RC1) -> 2021-03 (4.19.0) on RC2
[x] packages/*/epp.website.xml for product name= line
[x] RELEASE_NAME, RELEASE_MILESTONE, RELEASE_DIR, SIMREL_REPO Variables in parent pom releng/org.eclipse.epp.config/parent/pom.xml
SIMREL_REPO should be updated to the URL published in the email to cross-project-issues announcing SimRel repo is ready for EPP build
[ ] TODO can this part below be automated
See comment in the pom.xml file around eclipse.simultaneous.release.name
On R build, for eclipse.simultaneous.release.name remove qualifier i.e. it should be 2020-12 (4.18.0)
On M1 build add the qualifier back in, for eclipse.simultaneous.release.name remove qualifier i.e. it should be 2020-12 M1 (4.18.0 M1)
[ ] TODO can this be automated on release builds release.xml template in releng/org.eclipse.epp.config/tools/promote-a-build.sh needs updating
[ ] Update SIMREL_REPO in releng/org.eclipse.epp.config/parent/pom.xml if not done above.
[x] Update the build qualifiers to ensure that packages are all updated. See this gerrit for an example. To do this run releng/org.eclipse.epp.config/tools/setGitDate (link) script. This script will make a local commit you need to push.
[x] Run a CI build that includes the above changes.
[x] Disable the CI build so that the build results are not overwritten while doing the promotion. You can disable the project once it has fully started running, you don't have to wait for the build to finish.
[x] Check that there are no unexpected warnings in the console output. Especially look for warnings about failure to sign.
The following warnings are known to be OK but ideally should be fixed at some point
Warnings about Mirror tool seem to be ok and can be ignored. In a historically good build there is one [WARNING] Mirror tool: Messages while mirroring artifact descriptors. per package
A terminally deprecated method in java.lang.System has been called is OK when it is about setSecurityManager from ANT. When the security manager goes away for real we'll have to resolve this issue.
The digest algorithms (md5) used to verify is OK to ignore because we pull from SimRel. Over time there should be less of these warnings as projects rebuild their old repos to have modern signing. These warnings are typically seen on bundles which are old, such as org.eclipse.update.feature,org.eclipse.license,2.0.2.v20181016-2210
No digest algorithm is available to verify download is OK to ignore when the bundles are the ones generated by the EPP build itself (such as org.eclipse.epp.package.common.feature or epp.package.cpp.executable.gtk.linux.aarch64)
Other warnings may be fine as well, as of the writing of this note there are 206 warnings in the build.
If warnings about signings occur that leave the dmg unsigned and the build does not fail, please reopen Bug 567916
[x] Run the Notarize MacOSX Downloads CI job to notarize DMG packages on download.eclipse.org. _This can be done after promotion if time is tight or the notarization fails repeatedly. See Bug 571669 for an example of failures._
[x] Check the build script output to make sure that the curl calls were successful (e.g. no curl: (92) HTTP/2 stream 0 was not closed cleanly: INTERNAL_ERROR (err 2) messages) - If there is an error like the above the .dmg file that is copied to download.eclipse.org is corrupt. Run notarize-prepare-to-redo to rename the -signed file back to -tonotarize and then re-run the notarize job
Other notes about notarization
NOTE It seems perfectly normal that the notarize job needs to be run multiple times as so many notarization attempts fail due to 500 and 000 response codes from the notarization server. See Bug 571669
NOTE Sometimes the notarization server has an error that causes a failure that requires Webmaster support. Error looks like "an existing transporter instance is currently uploading this package". To resolve request assistance in Bug 573875 (like what was done in Comment 11 of that bug). (TODO it may be possible to workaround this error by always using a different random ID when doing the notarization.)
[x] Made sure filenames contain expected build name and milestone, e.g. 2020-03-M2
[x] Splash screen says expected release name (with no milestone), e.g. 2020-03
[x] Help -> About says expected build name and milestone, e.g. 2020-03-M2
[x] org.eclipse.epp.package.* features and bundles have the timestamp of the forced qualifier update or later
[x] Upgrade from previous release works. To test the upgrade an equivalent to the simrel release composite site needs to done. Add the following software sites to available software, check for updates and then make sure stuff works. In particular check error log and that core features (Such as JDT, Platform) have been upgraded.
https://download.eclipse.org/staging/2024-03/ - NOTE Use SIMREL_REPO if the staging repo has been updated since the SIMREL_REPO location was created.
[x] Edit Jenkins Build Information and name it (e.g. 2020-03 M3)
[x] In the evening Ottawa time, run the Promote a Build CI job to prepare build artifacts and copy them to download.eclipse.org
[ ] Optional - useful when testing changes to the promotion scripts: Run the build once in DRY_RUN mode to ensure that the output is correct before it is copied to download.eclipse.org.
This is done late in the day to try and reduce impact of adding dozens of GB on the download server and having all the mirrors start to pick it up right away. See epp-dev emails that led to this decision.
The DRY_RUN can be done earlier in the day and is a good way to increase the chance that the final promotion step will be successful.
[x] Run the Notarize MacOSX Downloads CI job to notarize DMG packages on download.eclipse.org if the promoted build was unstable
[x] Update SIMREL_REPO to the staging repo so CI builds run against CI of SimRel (e.g. see this gerrit)
[x] Send email to epp-dev to request package maintainers test it. The email is templated in email.txt in the release directory.
[x] Archive old milestones/RCs so that they don't accumulate on the mirrors
[ ] 24 Hours before Final release Make sure files are in final location to allow downloads to mirror
[ ] Tag the release, e.g. with 2020-03_R. Example command line: git tag --annotate 2020-03_R -m"2020-03 Release" 1b7a1c1af156e3ac57768b87be258cd22b49456b
[ ] rename the provisional release milestone to final directory (E.g. 2020-09/202009101200 -> 2020-09/R (to match what is in release.xml) - this only applies to downloads, not to packages
This can be done with a script like TODO: make a job for this :
ssh genie.packaging@projects-storage.eclipse.org /bin/bash << EOF
set -u # run with unset flag error so that missing parameters cause build failure
set -e # error out on any failed commands
set -x # echo all commands used for debugging purposes
mv -v /home/data/httpd/download.eclipse.org/technology/epp/downloads/release/2021-03/202103121200 /home/data/httpd/download.eclipse.org/technology/epp/downloads/release/2021-03/R
touch /home/data/httpd/download.eclipse.org/technology/epp/downloads/release/2021-03/R/*
EOF
[ ] The next release sub-directory needs to be created immediately after a release, i.e. when 2019-12 was released, a directory 2020-03 had been created with an empty p2 composite repository pointing to 2019-12 until M1. (Use Job https://ci.eclipse.org/packaging/job/epp-createNextRelease/) On M1 release day this changes to a composite p2 repository with M1 content. On other release days, add the new releases as children and on final release this changes to a composite with just the one child.
The EPP Release Process
This guide contains the step-by-step process to complete an EPP release.
The individual releases are tracked with endgame issues on GitHub issues. For each release (M1, M2, M3, RC1, RC2) an endgame ticket is created with the appropriate contents from the rest of this document:
EPP releases happen for each milestone and release candidate according to the Eclipse Simultaneous Release Plan.
Steps for all Milestones and RCs:
epp.website.xml-incubationand(includes Incubating components)are not used in packageMetaData anymore (See Bug 564214)url=(notice the blank before url) inepp.website.xmlto see which ones are contained in the different packages.epp.productfiles.*.product/p2.inffiles.iconsroot directory.gitk -- **/epp.product **/p2.infand make sure every change to included features in epp.product has a matching change in p2.inf. You should only have to look as far back as the last M or RC build.[releng] Prepare repo for 2020-12 M1. In particular, check:2021-03-R->2021-06-M1, on RC2 set it toRthe qualifier e.g.2021-03-RC1->2021-03-R). Except foreclipse.simultaneous.release.namewhich should go from2021-03 (4.19.0)->2021-06 M1 (4.20.0 M1)on M1 and2021-03 RC1 (4.19.0 RC1)->2021-03 (4.19.0)on RC2packages/*/epp.website.xmlforproduct name=lineRELEASE_NAME,RELEASE_MILESTONE,RELEASE_DIR,SIMREL_REPOVariables in parent pomreleng/org.eclipse.epp.config/parent/pom.xmlSIMREL_REPOshould be updated to the URL published in the email to cross-project-issues announcing SimRel repo is ready for EPP buildeclipse.simultaneous.release.nameeclipse.simultaneous.release.nameremove qualifier i.e. it should be2020-12 (4.18.0)eclipse.simultaneous.release.nameremove qualifier i.e. it should be2020-12 M1 (4.18.0 M1)releng/org.eclipse.epp.config/tools/promote-a-build.shneeds updatingSIMREL_REPOinreleng/org.eclipse.epp.config/parent/pom.xmlif not done above.releng/org.eclipse.epp.config/tools/setGitDate(link) script. This script will make a local commit you need to push.[WARNING] Mirror tool: Messages while mirroring artifact descriptors.per packageA terminally deprecated method in java.lang.System has been calledis OK when it is about setSecurityManager from ANT. When the security manager goes away for real we'll have to resolve this issue.The digest algorithms (md5) used to verifyis OK to ignore because we pull from SimRel. Over time there should be less of these warnings as projects rebuild their old repos to have modern signing. These warnings are typically seen on bundles which are old, such asorg.eclipse.update.feature,org.eclipse.license,2.0.2.v20181016-2210No digest algorithm is available to verify downloadis OK to ignore when the bundles are the ones generated by the EPP build itself (such asorg.eclipse.epp.package.common.featureorepp.package.cpp.executable.gtk.linux.aarch64)curl: (92) HTTP/2 stream 0 was not closed cleanly: INTERNAL_ERROR (err 2)messages) - If there is an error like the above the .dmg file that is copied to download.eclipse.org is corrupt. Run notarize-prepare-to-redo to rename the -signed file back to -tonotarize and then re-run the notarize job2020-03-M22020-032020-03-M2org.eclipse.epp.package.*features and bundles have the timestamp of the forced qualifier update or laterhttps://download.eclipse.org/staging/2024-03/- NOTE UseSIMREL_REPOif the staging repo has been updated since theSIMREL_REPOlocation was created.https://download.eclipse.org/technology/epp/staging/repository/2020-03 M3)DRY_RUNmode to ensure that the output is correct before it is copied to download.eclipse.org.DRY_RUNcan be done earlier in the day and is a good way to increase the chance that the final promotion step will be successful.SIMREL_REPOto the staging repo so CI builds run against CI of SimRel (e.g. see this gerrit)git tag --annotate 2020-03_R -m"2020-03 Release" 1b7a1c1af156e3ac57768b87be258cd22b49456b