Release process

This page explains policies related to releases in the Eclipse ESCET project, as well as step by step instructions for the various processes involved with releases, from preparing for a release to actually releasing it.

Policies:

Step by step instructions:

Release policy

The Eclipse ESCET project uses a time-based release policy. We generally release every three months, at the end of each quarter, typically on its last working day.

We may however deviate from this. For instance, we may release earlier at the end of the year, well before the Christmas period.

Eclipse ESCET has several types of releases:

  • Nightlies: This involves regular releases of new developments. Strictly speaking, these are not nightlies, as they are not released every night, but instead whenever a new change is merged into the develop branch of ESCET’s main Git repository.

  • Milestones: This involves intermediate releases of the current development progress, typically released around halfway a release cycle. For instance, v1.0-M1 is the first milestone release for version 1.0.

  • Release candidates: This involves previews that are used for testing prior to a final release. If all is well, the final release is then functionally identical to the release candidate. For instance, v1.0-RC1 is the first release candidate for version 1.0.

  • Final releases: This involves a final release for a version of the ESCET toolkit. For instance, v1.0 is the final release for version 1.0.

Release retention policy

The Eclipse ESCET project has the following retention policies for its different types of releases:

  • Nightlies: Each nightly releases is overwritten by the next nightly release. Only the most recent nightly release is thus available.

  • Milestones: Milestone releases are removed when the final release of the next version is released. Therefore, directly after a final release, only the milestone releases of that version are available. During a release cycle, the milestone releases of the in-progress release and the previous release are available. For instance, when v2.0 is released, milestone releases v1.0-M1, v1.0-M2, and so on, will be removed.

  • Release candidates: Release candidates are removed when the final release of the next version is released. Therefore, directly after a final release, only the release candidates of that version are available. During a release cycle, the release candidates of the in-progress release and the previous release are available. For instance, when v2.0 is released, release candidates v1.0-RC1, v1.0-RC2, and so on, will be removed.

  • Final releases: Final releases are kept indefinitely.

Planning for a next version

For a new version (not milestone or release candidate), follow these steps. Perform them well in advance of starting work on the version, i.e. while still working on the previous version:

  • Create a new release record:

    • Go to https://projects.eclipse.org/projects/technology.escet.

    • Log in with your Eclipse Foundation account using the link at the top-right of the page.

    • Click the Create a new release link in the bar at the right.

    • Set the planned release date and give the release a name, e.g. 0.1, 0.1.1 or 1.0.

    • Click Create and edit.

    • For Description, click the Source button in the toolbar of the editor. Then enter <p>See <a href="https://gitlab.eclipse.org/eclipse/escet/escet/-/milestones/NNN">Eclipse ESCET GitLab vN.N issues</a> for more information.</p>. Replace NNN by the actual GitLab milestone number to ensure a correct URL. Replace vN.N by the version, e.g. v0.1, v0.1.1 or v1.0.

    • Change the Release type if applicable.

    • Click Save.

  • Create a GitLab milestone:

  • Create release issues:

    • Go to https://gitlab.eclipse.org/eclipse/escet/escet/-/issues.

    • Sign in with your Eclipse Foundation account using the link at the top-right of the page.

    • Click New issue.

    • For Title enter Release vN.N-M1. Replace N.N by the actual release record version, e.g. 0.1, 0.1.1 or 1.0.

    • For Milestone select the just created GitLab milestone.

    • For Labels select RelEng/DevOps and Type::Enhancement.

    • Click Create issue.

    • Repeat these steps to create issues for the release candidate (Release vN.N-RC1) and final release (Release vN.N).

    • Repeat these steps to create an issue for preparing the Git repository for development of the new version (Prepare Git repo for vN.N development).

    • If a progress review is needed, schedule one if one is not yet scheduled.

Preparing Git repository for a next version

To prepare the Git repository for the next version (not a milestone or release candidate), follow these steps:

  • Run in the root of the Git repository the command mvn org.eclipse.tycho:tycho-versions-plugin:N.N.N:set-parent-version -DnewParentVersion=<new-version>, where <new-version> is replaced by the new version (e.g. 0.2.0.qualifier), and N.N.N by the Tycho version (e.g., 4.0.1, see .mvn/extensions.xml for the version currently in use). This replaces most version numbers automatically. Check all changes to ensure no versions are updated that should not be updated.

  • Verify that the product version in org.eclipse.escet.product/escet.product is properly updated. The old version should no longer be present. This should be automatic.

  • Verify that the feature version of the product feature in org.eclipse.escet.product/escet.product is properly updated. The old version should no longer be present. This should be automatic.

  • Verify that the version of each import feature in all feature.xml files is properly updated. The old version should no longer be present. This should be automatic.

  • Verify that the Bundle-Version of all MANIFEST.MF files in org.eclipse.escet.* projects are properly updated. The old version should no longer be present. This should be automatic.

  • Manually replace in all MANIFEST.MF files the regex org\.eclipse\.escet\.([a-z0-9\.]+);bundle-version="<old-version>" by org.eclipse.escet.\1;bundle-version="<new-version>", where <old-version> and <new-version> are replaced by actual versions, e.g. 0.1.0. Check for unintended changes. Search for the old version in all manifests to ensure none remain.

  • In all documentation sets, add a new section to the release notes for the new version, before the existing versions:

    === Version 0.2

TBD

  • Verify that the <version> of a POM and its parent in each pom.xml are properly updated. The old version should no longer be present. This should mostly be automatic. Manually adapt it where necessary.

  • Verify that the version of all feature.xml files in org.eclipse.escet.* projects are properly updated. The old version should no longer be present. This should be automatic.

  • Verify that the license-feature-version of all feature.xml files in org.eclipse.escet.* projects are properly updated. The old version should no longer be present. This should be automatic.

  • Manually search for the old version in all features.xml files to ensure none remain.

  • Search the entire Git repository (all projects) for the old version number and update anything that still requires updating.

  • Test that the build works.

Working on a release

The work for the next release (milestone, release candidate, or final release) is done in the develop branch. See the development process for more information.

Note that for each version at least one milestone release and at least one release candidate are required before a final release.

Preparing a release

Once the work on develop is done for a release (milestone, release candidate, or final release), follow these steps to prepare for the release:

  • Double check that the release notes of all documentation sets have been updated for all end-user visible changes.

  • For a final release add the release date to the release notes.

  • For a final release ensure the TBD indication is removed in the release notes of all documentation sets.

  • For a final release ensure that all IP is accounted for and all relevant Eclipse Foundation IP team issues in IPLab have been approved by the Eclipse Foundation IP team.

  • For a final release ensure that a progress review has been successfully completed no more than one year ago.

Preparing a progress review

For a final release a progress review (or release review) must have been successfully completed no more than one year ago. Follow these steps to prepare a progress review:

  • Read the official information on progress reviews in the Eclipse Project Handbook.

  • The Eclipse Foundation now schedules a new progress review one year after the current one completes, by creating a corresponding GitLab issue in the EMO’s GitLab. So, there should be no need to schedule one ourselves. But, if the Eclipse Foundation did not schedule one, we should ask the EMO to schedule one:

    • Send an email to emo@eclipse.org, with a CC to escet-dev@eclipse.org.

      • As subject, use Please schedule the yearly Eclipse ESCET progress review.

      • As message, use the following template:

        Please schedule the yearly Eclipse ESCET progress review.

Kind regards,
<Your Name>
Eclipse ESCET <your role>

        Replace <Your Name> by your full name (first and last name). Replace <your role> by either project lead or project committer.

  • Create an Eclipse ESCET issue to track the progress review:

    • Give it the title Eclipse ESCET progress review YYYY-MM-DD, with YYYY-MM-DD the due date of the EMO’s GitLab issue.

    • As content, use the following template:

      The EMO created a progress review for YYYY-MM-DD:
* https://projects.eclipse.org/projects/technology.escet/reviews/YYYY.MM-progress-review
* https://gitlab.eclipse.org/eclipsefdn/emo-team/emo/-/issues/NNN

      Replace YYYY-MM-DD by the due date of the EMO’s GitLab issue. Replace YYYY.MM by the due month of the EMO’s GitLab issue. Replace NNN by the EMO’s GitLab issue that tracks the progress review. Check that the links work correctly.

  • Request PMC approval two weeks in advance:

    • Go to https://accounts.eclipse.org/mailing-list/technology-pmc and subscribe to the Technology PMC mailing list, if not yet subscribed. Subscription is necessary to post to the list.

    • Send an email to technology-pmc@eclipse.org, with a CC to escet-dev@eclipse.org.

      • As subject, use Request progress review approval for the Eclipse ESCET project.

      • As message, use the following template:

        The Eclipse ESCET project hereby requests approval for its annual progress review.

See https://gitlab.eclipse.org/eclipsefdn/emo-team/emo/-/issues/NNN

Kind regards,
<Your Name>
Eclipse ESCET <your role>

        Replace NNN by the EMO’s GitLab issue that tracks the progress review. Replace <Your Name> by your full name (first and last name). Replace <your role> by either project lead or project committer.

  • Update the progress review issue description with the following template:

    See the following pages for submitted materials and approval:
* PMC approval request: https://www.eclipse.org/lists/technology-pmc/msgNNN.html
* PMC approval: https://www.eclipse.org/lists/technology-pmc/msgNNNN.html

    Replace NNN and NNNN by the corresponding mailing list message numbers. Consult the Technology PMC mailing list archive to find the messages and their message numbers.

  • Ensure the progress review is successful before performing the release.

Performing a release

To perform a release (milestone, release candidate, or final release), i.e. actually release it, follow these steps:

  • Merge develop to master:

    • Since master is a protected branch for the Eclipse ESCET GitLab, a GitLab merge request is the only way to update it.

    • Create a GitLab merge request from develop to master.

    • For Title enter #NNN develop to master for vN.N. Replace #NNN by the relevant issue number. Replace N.N by the release version, e.g. 1.0-M1, 1.0-RC1 or 1.0.

    • Replace the automatically generated but incomplete Description by Addresses #NNN. Replace #NNN by the relevant issue number.

    • For Milestone select the relevant milestone.

    • For Labels select RelEng/DevOps and Type::Enhancement.

    • Click Create merge request.

    • Wait for the builds on Jenkins to successfully complete and press Merge. Alternatively, press Merge when pipeline succeeds to automatically merge the merge request once the build succeeds.

  • Add a tag on the commit in master that is to be released. Only version tags with a specific syntax will be picked up by Jenkins to be released. For instance, use v0.1, v0.1.1, v2.0, etc for releases, v0.1-M1 for a milestone build, or v0.1-RC1 for a release candidate.

    Add the tag via GitLab, at https://gitlab.eclipse.org/eclipse/escet/escet/-/tags/new. Use the Tag name also as Message. Make sure to select master as branch from which to create the tag. Click Create tag to create the new tag.

  • Add a GitLab release for the new tag, at https://gitlab.eclipse.org/eclipse/escet/escet/-/releases/new. Select the tag you just created under Tag name. Set the Release title and Release notes to the tag name. Select the relevant milestone under Milestones. Click Create release to create the new release.

  • Go to Jenkins, at https://ci.eclipse.org/escet/job/ESCET%20build/. Log in to Jenkins by clicking on the link at the top-right of the page. Select Scan GitLab Project Now to ensure Jenkins picks up the new tag.

  • Go to https://ci.eclipse.org/escet/job/ESCET%20build/view/tags/ to see the new tag on Jenkins. Manually trigger a build for the tag, by clicking the Schedule a build for …​ icon in the row for the tag. Jenkins will then automatically build and release a new version from that tag.

  • All releases are available at https://download.eclipse.org/escet/. For a version v0.1, the downloads will be located at https://download.eclipse.org/escet/v0.1.

    • End users should however be referred to https://eclipse.dev/escet/download.html instead of download.eclipse.org. The buttons on this web page serve downloads via a mirror script. This ensures that a nearby mirror is selected, for faster downloads. It also ensures that downloads are counted in the download statistics. Furthermore, it transparently handles files moved from download.eclipse.org to archive.eclipse.org.

    • According to the Eclipse Foundation Wiki page IT Infrastructure Doc, "Once your files are on the download.eclipse.org server, they are immediately available to the general public. However, for release builds, we ask that you wait at least four hours for our mirror sites to fetch the new files before linking to them. It typically takes a day or two for all the mirror sites to synchronize with us and get new files." Immediately after the downloads being available, downloading them may thus be slower, even if the mirror script is used.

  • Jenkins will automatically push the website for the new release to the website Git repository, in a directory for the specific release. For a version v0.1, the website can be accessed at https://eclipse.dev/escet/v0.1. It may take a few minutes for the new commit to the Git repository to be synced to the webserver. It may take up to an hour for the website of the new version to become available, due to browser caches and the Eclipse Foundation webserver using a max-age of 3600 seconds for some files.

  • For a final release with a version number higher than that of the current standard visible website (at https://eclipse.dev/escet), promote the newly released website to be the new standard visible website:

    • These steps assume that you’ve set up an Eclipse ESCET development environment, using the standard instructions, at <path-to-dev-env>.

    • Open a terminal.

    • Execute cd <path-to-dev-env>/git to go to the directory of your development environment with Git repositories.

    • Clone the Eclipse ESCET website Git repository by executing git clone https://gitlab.eclipse.org/eclipse/escet/escet-website.git.

    • Execute cd escet-website to enter the directory that contains the new clone.

    • Execute ../escet/misc/website/switch-standard-visible-website.bash vN.N "Full Name" "some@example.com", with appropriate substitutions, to replace the standard visible website:

      • Replace vN.N with the website release version that is to become the standard visible website, e.g., v0.1, v1.0-M1 or v1.1.0-RC1.

      • Replace Full Name by your full name (first name and last name) as registered in your Eclipse Foundation account, e.g., John Smith.

      • Replace some@example.com by your email address as registered in your Eclipse Foundation account.

    • As indicated, review the new commit. If it is OK, push it by executing git push.

    • Check that the changes are correctly registered by GitLab, at https://gitlab.eclipse.org/eclipse/escet/escet-website/-/commits/master.

    • Remove the website repository clone, by executing cd .. and rm -rf escet-website.

    • It may take a few minutes for the Git repository to be synced to the webserver. The standard visible website can be accessed at https://eclipse.dev/escet. It may take up to an hour for the website of the new version to become available, due to browser caches and the Eclipse Foundation webserver using a max-age of 3600 seconds for some files.

  • Since we can’t ask our end users to force refresh every webpage, nor to clear their browser’s cache, wait an hour and five minutes before proceeding with the next step.

  • Inform others about the new release:

    • In the relevant GitLab issue, for final releases, post the following comment, where N.N is to be replaced by the actual release version, e.g. 0.1 or 1.0:

      I just released vN.N:

- https://eclipse.dev/escet/
- https://eclipse.dev/escet/download.html
- https://eclipse.dev/escet/release-notes.html

And here are the permalinks:

- https://eclipse.dev/escet/vN.N
- https://eclipse.dev/escet/vN.N/download.html
- https://eclipse.dev/escet/vN.N/release-notes.html

Note that mirrors may still need to sync, so downloads may be a bit slower until then.

    • In the relevant GitLab issue, for milestones and release candidates, post the following comment, where N.N-NNN is to be replaced by the actual release version, e.g. 0.1-M1 or 1.0-RC1:

      I just released vN.N-NNN:

- https://eclipse.dev/escet/vN.N-NNN
- https://eclipse.dev/escet/vN.N-NNN/download.html
- https://eclipse.dev/escet/vN.N-NNN/release-notes.html

Note that mirrors may still need to sync, so downloads may be a bit slower until then.

    • Also send an email to escet-dev@eclipse.org with similar content.

  • Clean up after the release:

    • Close the GitLab issue for the release.

    • For a final release, ensure all issues in the GitLab milestone are closed.

    • For a final release, close the GitLab milestone.

  • Remove/archive old releases.

Removing/archiving old releases

To prevent unnecessary disk space usage, old releases can be archived and removed. Below the policy and steps for both of them are explained. These steps are to be followed after performing a release.

For every release, including milestones and release candidates:

  • Remove the builds for all previously built tags, thus excluding the tag of the release that was just built:

    • In Jenkins, while logged in, go to https://ci.eclipse.org/escet/job/ESCET%20build/view/tags/.

    • Select the tag name in the Name column to go the tag’s page.

    • There, on the left, the various builds are indicated by #n, with n some number.

    • In the drop down menu of a build, select Delete build #n to remove it.

    • When asked to confirm, click Yes.

For every final release, thus excluding milestones and release candidates:

  • Identify the milestone and release candidate versions to remove. We remove all milestones and release candidates of the previous version and older. E.g. for v0.2, we remove v0.1-M1, v0.1-M2, v0.1-RC1, etc.

  • Identify the final release versions to archive. We archive all releases older than the current and previous release, but never remove them. E.g. for v0.3 we archive v0.1 and older, but keep v0.2.

  • Remove the websites of the identified milestone and release candidate versions:

    • These steps assume that you’ve set up an Eclipse ESCET development environment, using the standard instructions, at <path-to-dev-env>.

    • Open a terminal.

    • Execute cd <path-to-dev-env>/git to go to the directory of your development environment with Git repositories.

    • Clone the Eclipse ESCET website Git repository by executing git clone https://gitlab.eclipse.org/eclipse/escet/escet-website.git.

    • Execute cd escet-website to enter the directory that contains the new clone.

    • For each website version to remove:

      • Execute ../escet/misc/website/remove-website-version.bash vN.N "Full Name" "some@example.com", with appropriate substitutions, to remove the website:

        • Replace vN.N with the website milestone or release candidate version to remove, e.g.,v0.9-M1 or v1.1.0-RC1.

        • Replace Full Name by your full name (first name and last name) as registered in your Eclipse Foundation account, e.g., John Smith.

        • Replace some@example.com by your email address as registered in your Eclipse Foundation account.

      • As indicated, review the new commit. If it is OK, push it by executing git push.

    • If successful you should see the changes on GitLab, at https://gitlab.eclipse.org/eclipse/escet/escet-website/-/commits/master.

    • Remove the website repository clone, by executing cd .. and rm -rf escet-website.

    • It may take a few minutes for the Git repository to be synced to the webserver, and for the removed websites to no longer be available online. Depending on browser cache settings and other factors, it may be necessary to force refresh your browser for it to pick up the changes on the server.

  • Remove the downloads of the identified milestone and release candidate versions:

    • Go to https://download.eclipse.org/escet/.

    • Make sure you are logged in. This should make check-boxes appear.

    • Select the folders to archive (before subsequent removal) and click the Move selected to archive.eclipse.org button. It may take a few minutes for archiving to complete.

    • Go to https://archive.eclipse.org/escet/.

    • Make sure you are (still) logged in. This should make check-boxes appear.

    • Select the folders to delete and click the Delete selected permanently button. It may take a few minutes for deleting to complete.

  • Archive the downloads of the identified final versions:

    • Note that links to download.eclipse.org transparently redirect to archive.eclipse.org for archived files. We can therefore safely archive final versions, without breaking links to update sites that use download.eclipse.org.

    • Go to https://download.eclipse.org/escet/.

    • Make sure you are logged in. This should make check-boxes appear.

    • Select the folders to archive and click the Move selected to archive.eclipse.org button. It may take a few minutes for archiving to complete.

    • Do not remove final versions. They should be kept forever.