Release process
This page explains step by step the various processes involved from preparing for a release to actually releasing it. The following topics are covered:
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.
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
or1.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>
. ReplaceNNN
by the actual GitLab milestone number to ensure a correct URL. ReplacevN.N
by the version, e.g.v0.1
,v0.1.1
orv1.0
. -
Change the Release type if applicable.
-
Click Save.
-
-
Create a GitLab milestone:
-
Go to https://gitlab.eclipse.org/eclipse/escet/escet/-/milestones.
-
Sign in with your Eclipse Foundation account using the link at the top-right of the page.
-
Click New milestone.
-
For Title enter the version, e.g.
v0.1
,v0.1.1
orv1.0
. -
For Description enter
See also https://projects.eclipse.org/projects/technology.escet/releases/N.N.
. ReplaceN.N
by the actual release record version, e.g.0.1
,0.1.1
or1.0
. -
For Start date select the first day after the Due date of the previous version.
-
For End date select the same date as the planned release date of the release record.
-
Click Create 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
. ReplaceN.N
by the actual release record version, e.g.0.1
,0.1.1
or1.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 release review is needed, create an issue for that as well (
Release review for vN.N
).
-
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_escet.sh org.eclipse.tycho:tycho-versions-plugin:set-version -DnewVersion=<new-version>
, where<new-version>
is replaced by the new version, e.g.0.2.0.qualifier
. 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
inorg.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 inorg.eclipse.escet.product/escet.product
is properly updated. The old version should no longer be present. This should be automatic. -
Verify that the
Bundle-Version
of allMANIFEST.MF
files inorg.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 regexorg\.eclipse\.escet\.([a-z0-9\.]+);bundle-version="<old-version>"
byorg.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 eachpom.xml
are properly updated. The old version should no longer be present. This should mostly be automatic. Manually adapt it where necessary.-
Manually adapt the version in
org.eclipse.escet.releng.configuration/pom.xml
. -
Manually adapt the parent version in
org.eclipse.escet.root/pom.xml
. Also remove the version for the pom itself, to prevent a warning that the version of the pom and its parent are identical.
-
-
Verify that the
version
of allfeature.xml
files inorg.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 allfeature.xml
files inorg.eclipse.escet.*
projects are properly updated. The old version should no longer be present. This should be automatic. -
Manually replace in all
feature.xml
files the regex<import feature="([^"]+)" version="<old-version>"/>
by<import feature="\1" version="<new-version>"/>
, where<old-version>
and<new-version>
are replaced by actual versions, e.g.0.1.0.qualifier
. Check for unintended changes. -
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 CQs and IP Team GitLab issues have been approved by the Eclipse Foundation IP team.
-
For a final release ensure that a release review has been successfully completed no more than one year ago.
Preparing a release review
For a final release a release review must have been successfully completed no more than one year ago. Follow these steps to prepare a release review:
-
Read the official information on release reviews in the Eclipse Project Handbook. In particular, note that the Eclipse Foundation "schedule[s] reviews to conclude on the first and third Wednesdays of the month. Your release date does not have to coincide with the review date (you can set the release date as necessary). The review must, however, conclude successfully before you can make the release official."
-
Update the release record, including the release review information:
-
Go to the release record at
https://projects.eclipse.org/projects/technology.escet/releases/N.N
. ReplaceN.N
by the actual release record version, e.g.0.1
,0.1.1
or1.0
. -
Click the Edit tab.
-
Change the information as desired, using previous release records as inspiration.
-
For the Description, use the following template:
<p>This release [describe the release in a few sentences].</p> <p>For more information:</p> <ul> <li>Eclipse ESCET vN.N-NNN release notes <ul> <li><a href="https://www.eclipse.org/escet/vN.N-NNN/release-notes.html">ESCET toolkit release notes</a></li> <li><a href="https://www.eclipse.org/escet/vN.N-NNN/chi/release-notes.html">Chi release notes</a></li> <li><a href="https://www.eclipse.org/escet/vN.N-NNN/cif/release-notes.html">CIF release notes</a></li> <li><a href="https://www.eclipse.org/escet/vN.N-NNN/tooldef/release-notes.html">ToolDef release notes</a></li> </ul> </li> <li><a href="https://gitlab.eclipse.org/eclipse/escet/escet/-/milestones/NN">Eclipse ESCET GitLab vN.N issues</a></li> </ul>
Replace
N.N-NNN
by the latest release candidate version of the release to be reviewed, e.g.0.1-RC1
,0.1.1-RC2
or1.0-RC1
. ReplaceNN
by the actual GitLab milestone number, e.g.,1
,2
or3
. ReplaceN.N
by the final release version, e.g.0.1
,0.1.1
or1.0
. -
Click Save.
-
-
Submit the IP Log:
-
Go to https://projects.eclipse.org/projects/technology.escet.
-
Ensure you’re logged in, as an ESCET project committer.
-
In the right sidebar, click Generate IP Log.
-
For Respin, select None, this is a new IP Log review request.
-
For Required by date, select the date one week before the review conclusion date.
-
For Release select the relevant release.
-
It is not necessary to write any Comments.
-
Click Submit for review.
-
Note the message at the top of the page, indicating that a CQ was created, to track the approval of the IP Log by the Eclipse Foundation IP team.
-
-
Request PMC approval:
-
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 toescet-dev@eclipse.org
.-
As subject, use
Request release approval for Eclipse ESCET vN.N release
. ReplacevN.N
by the release version, e.g.v0.1
,v0.1.1
orv1.0
. -
As message, use the following template:
The Eclipse ESCET project hereby requests approval for the vN.N release. See https://projects.eclipse.org/projects/technology.escet/releases/N.N Kind regards, <Your Name> Eclipse ESCET <your role>
Replace
N.N
by the release version, e.g.0.1
,0.1.1
or1.0
. Replace<Your Name>
by your full name (first and last name). Replace<your role
> by eitherproject lead
orproject committer
.
-
-
-
Ask the EMO to schedule the release review and make it public:
-
Go to the release record at
https://projects.eclipse.org/projects/technology.escet/releases/N.N
. ReplaceN.N
by the actual release record version, e.g.0.1
,0.1.1
or1.0
. -
Observe how Schedule a review for this release is indicated at the top of the page.
-
Click the review link as part of that text.
-
For Review dates select the review conclusion date.
-
Click Schedule a review.
-
Observe how the text has changed to This review is pending; contact The Eclipse Management Organization to make it public.
-
Send an email to
emo@eclipse.org
, with a CC toescet-dev@eclipse.org
.-
As subject, use
Please schedule the Eclipse ESCET vN.N Release Review
. ReplacevN.N
by the release version, e.g.v0.1
,v0.1.1
orv1.0
. -
As message, use the following template:
See https://projects.eclipse.org/projects/technology.escet/reviews/N.N-release-review Kind regards, <Your Name> Eclipse ESCET <your role>
Replace
N.N
by the release version, e.g.0.1
,0.1.1
or1.0
. Replace<Your Name>
by your full name (first and last name). Replace<your role
> by eitherproject lead
orproject committer
.
-
-
-
Update the release review issue description with the following template:
See the following pages for submitted materials and approval: * Release record and review materials: https://projects.eclipse.org/projects/technology.escet/releases/N.N * IP Log approval issue: https://dev.eclipse.org/ipzilla/show_bug.cgi?id=NNN * PMC approval request: https://www.eclipse.org/lists/technology-pmc/msgNNNN.html * PMC approval: https://www.eclipse.org/lists/technology-pmc/msgNNNNN.html * EMO release review scheduling request: https://www.eclipse.org/lists/escet-dev/msgNNNNNN.html * EMO release review tracking issue: https://gitlab.eclipse.org/eclipsefdn/emo-team/emo/-/issues/NN
Replace
N.N
by the release version, e.g.0.1
,0.1.1
or1.0
. ReplaceNNN
by the IP Log CQ issue number. ReplaceNNNN
,NNNNN
, andNNNNNN
by the corresponding mailing list message numbers. Consult the Technology PMC mailing list archive and the Eclipse ESCET dev mailing list archive to find the messages and their message numbers. ReplaceNN
by the GitLab issue number of the issue that will be created by the EMO to track the release review. -
Ensure the release 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
tomaster
:-
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
tomaster
. -
For Title enter
#NNN develop to master for vN.N
. Replace#NNN
by the relevant issue number. ReplaceN.N
by the release version, e.g.1.0-M1
,1.0-RC1
or1.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, usev0.1
,v0.1.1
,v2.0
, etc for releases,v0.1-M1
for a milestone build, orv0.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 athttps://download.eclipse.org/escet/v0.1
.-
End users should however be referred to https://eclipse.org/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 fromdownload.eclipse.org
toarchive.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 athttps://eclipse.org/escet/v0.1
. It may take a few minutes for the Git repository to be synced to the webserver and for the website for the new version to become available. -
If the website for the new release is to be the standard visible website for the project (at
https://eclipse.org/escet
), it has to be manually replaced. This is to ensure that a bugfix release for an older version doesn’t override the standard visible website. The following steps explain how to 'promote' a website for a specific version to become the 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
orv1.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 ..
andrm -rf escet-website
. -
It may take a few minutes for the Git repository to be synced to the webserver, and for the new standard visible website to become available. The standard visible website can be accessed at
https://eclipse.org/escet
. 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.
-
-
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
or1.0
:I just released vN.N: - https://eclipse.org/escet/ - https://eclipse.org/escet/download.html - https://eclipse.org/escet/release-notes.html And here are the permalinks: - https://eclipse.org/escet/vN.N - https://eclipse.org/escet/vN.N/download.html - https://eclipse.org/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
or1.0-RC1
:I just released vN.N-NNN: - https://eclipse.org/escet/vN.N-NNN - https://eclipse.org/escet/vN.N-NNN/download.html - https://eclipse.org/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
, withn
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 removev0.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 archivev0.1
and older, but keepv0.2
. -
Remove the websites of the identified milestone and release candidate versions:
-
Clone the Eclipse ESCET website Git repository using
git clone https://gitlab.eclipse.org/eclipse/escet/escet-website.git
. -
In the cloned repository, remove the folders corresponding to the milestone and release candidate versions.
-
Add all changes to be committed, e.g. by using
git add -A
. -
Commit the changes.
-
Use as commit message
Removed milestone and RC websites of release vN.N.
, replacingvN.N
by the release version, e.g.,v1.0
when removing versionsv1.0-M1
andv1.0-RC1
. -
Use the
--author
option to specify your full name (first name and last name) and email address as registered in your Eclipse Foundation account. Make sure to use double quotes around the entire argument, and<
and>
around the email address. -
E.g. use the following to commit the changes:
git commit --author "Full Name <some@example.org>" -m "Removed milestone and RC websites of release v1.0."
.
-
-
Push the changes to the Git server. E.g. use
git push
. -
If successful you should see the changes on GitLab, at https://gitlab.eclipse.org/eclipse/escet/escet-website/-/commits/master.
-
-
Remove the downloads of the identified milestone and release candidate versions:
-
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.
-
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 toarchive.eclipse.org
for archived files. We can therefore safely archive final versions, without breaking links to update sites that usedownload.eclipse.org
. -
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.
-