doc/Publishing.md
This guide details the steps for maintainers to release Eclipse Theia, including pre-release preparations, the release process, post-release steps, and troubleshooting.
Use GitHub Discussions for the announcement in the Category Release Announcements.
Title:
Eclipse Theia v{{version}}
Body:
Hey everyone π,
The Eclipse Theia v{{version}} release is scheduled for **{{releaseDate}}**.
Please use the Endgame issue below to track whatβs included.
If you have any nearly-complete PRs that should to be part of the release, please mention it in the endgame issue before we start:
- https://github.com/eclipse-theia/theia/issues/{{currentEndgameIssueNumber}}
We'll post updates when the release begins and again once itβs finished.
Please avoid merging pull requests until we confirm the release is complete.
Refer to this example for guidance.
Also send an email to the theia-dev mailing List (don't forget to add the link to the discussion):
Subject:
Eclipse Theia version v{{version}}
Body:
Hi everyone,
The Eclipse Theia v{{version}} release is scheduled for {{releaseDate}}!
You can follow the progress of the release here: https://github.com/eclipse-theia/theia/discussions/{{discussionNumber}}
Provide a heads-up to developers and the community a few hours before the release.
Use the Release discussion and post a comment to announce the patch release: https://github.com/eclipse-theia/theia/discussions/{{discussionNumber}}
We are preparing the patch release Eclipse Theia v{{version}}
Follow the endgame checklist here:
- https://github.com/eclipse-theia/theia/issues/{{patchEndgameIssueNumber}}
We'll post an update once the release is finished.
Check for tickets that need to be addressed when preparing the release:
nls updates before a release (example).Squash and merge to finalize it.bot/translation-update.Checkout master with the latest changes:
git pull
Confirm the latest changes are present:
git log
Create a branch with the pattern release/major.minor.x (e.g., release/1.55.x).
release/{{majorMinor}}.x
Add entries for non-breaking changes since the last release. Breaking changes should be added by the PR, not during the release.
Commit the changelog changes to the release branch with the message:
docs: update changelog for {{version}}
Format:
## 1.55.0 - 10/31/2024).[core]).[core] added support for Node 20.x [#pr-number](<link-to-pr>) - Contributed on behalf of x.<a name="breaking_changes_1.55.0">[Breaking Changes:](#breaking_changes_1.55.0)</a>).Announce that the release is starting as a comment in the Release discussion: https://github.com/eclipse-theia/theia/discussions/{{discussionNumber}}
The release will start now. We'll post an update once it has completed.
Please avoid merging pull requests until we confirm the release is complete.
NOTE: New @theia packages must be published once manually by a Theia committer before the publish workflow can publish them.
This is due to recent changes requiring trusted workflows for npm publishing.
It is recommend to first publish a next version of the new package, then we can publish the release properly via the recommended publish workflow.
npm login; NPM will prompt you for an OTP (one-time password) or security key).npm run publish:next
--yes parameter from the publish script, the publishing process will ask you to confirm each step before proceeding.Once it is published to NPM, please update the settings of this package as follows:
https://www.npmjs.com/package/@theia/<new-package>/accessPublisher > Select GitHub Actions publisher > Enter the required fields to our publish workflow (publish-ci.yml)Publishing access to Require two-factor authentication and disallow tokens (recommended)Optional: Trigger the publish workflow for the next version once to verify the workflow can publish the new package as expected.
NOTE: This publishing option is preferred, as the packages are built and signed on GitHub Actions with provenance using the trusted workflow for NPM publishing.
release/{{majorMinor}}.x)NOTE: In case the automatic publishing fails (e.g., some packages are not published if step 2.1.2 was missed) you can go to Option 2, performing the release locally. Already published packages of the version will be skipped and the missing ones will be published then.
Rebase and Merge.NOTE: Performing the release locally will publish unsigned packages to NPM.
Ensure the release branch is checked out (i.e., release/{{majorMinor}}.x).
Clean the working directory:
git clean -xdf
Build the changes:
npm install && npm run build
Confirm the changes are built (ensure @theia extensions have their lib/ folders).
The settings for publishing access were changed to the recommended: 'Require two-factor authentication and disallow tokens (recommended)'.
To publish locally, you need to:
npm login; NPM will prompt you for an OTP (one-time password) or security key).Optional: If you remove the --yes parameter from the publish scripts, the publishing process will ask you to confirm each step before proceeding..
For example, a sample publishing run could look like this:
npm run publish:next
lerna notice
...
lerna info
Found 1 package to publish:
- @theia/some-package => x.y.z
β Are you sure you want to publish these packages? Yes
lerna info publish Publishing packages to npm...
β This operation requires a one-time password: <enter your OTP>
lerna success published @theia/some-package x.y.z
lerna notice
lerna notice π¦ @theia/[email protected]
lerna notice === Tarball Contents ===
...
lerna notice
Successfully published:
- @theia/[email protected]
lerna success published 1 package
Done in ...s.
Perform the release:
npm run publish:latest
Select the appropriate version.
Verify the packages are published on npm and with the correct tag. (e.g., check the core package https://www.npmjs.com/package/@theia/core?activeTab=versions)
Remove the auth token:
npm logout
NOTE: For a patch release on an earlier version (e.g., 1.55.1 when 1.56.0 exists), use:
npm run publish:patch
For a patch to the current version use:
npm run publish:latest
Verify the packages are published on npm and with the correct tag. (e.g., check the core package https://www.npmjs.com/package/@theia/core?activeTab=versions)
Remove the auth token:
npm logout
Ensure the release branch is still checked out (i.e., release/{{majorMinor}}.x).
Update packages/core/README.md in a commit (example).
Commit message:
core: update re-exports for v{{version}}
Add other changes in a commit named v{version}.
Make sure to update ALL packages to the new version (search & replace)
Commit message:
v{{version}}
Push the branch.
native dependencies
Create a PR against main (not needed for patch releases): https://github.com/eclipse-theia/theia/compare
PR Title:
Theia v{{version}}
Rebase and Merge (DO NOT Squash and Merge).See for example: https://github.com/eclipse-theia/theia/pull/16333
Tag the publishing commit after merging (for patch releases, tag directly on the release branch):
git tag -a v{{version}} ${sha} -m "v{{version}}"
Note: The tag needs to be annotated otherwise it might break the publishing. Check that the output of the following command is tag and not commit.
git for-each-ref refs/tags | grep 'v{{version}}' | awk '{print $2}'
Push the tag:
git push origin v{{version}}
tag and input the release title from below.generate release notes for contributors and format like previous releases.changelog and breaking changes.latestRelease Title:
Eclipse Theia v{{version}}
tag and input the release title from below.Generate release notes for the changelog link.latest (Uncheck for a patch on an OLDER version!!).Release Title:
Eclipse Theia v{{version}}
Release Body:
Based on https://github.com/eclipse-theia/theia/tree/v{{majorMinor}}.X
Includes the following fixes:
- <list of commits>
**Full Changelog**: should be generated via 'Generate release notes'
Community releases follow the same procedure as the regular releases. Please follow 2.1 Performing a Release.
Release / Create a new release from the menu.
Release Date: Enter the date.Name: Enter the version (e.g., 1.55.0).deliverables (Link with text Release Notes).compatibility (Link with text Breaking Changes).Close the endgame issue: use the comment below as closing comment.
Update the discussion and comment in the Release discussion that the release is completed: https://github.com/eclipse-theia/theia/discussions/{{discussionNumber}}
The [{{version}} release](https://github.com/eclipse-theia/theia/releases/tag/v{{version}}) has completed, thank you to everyone that participated and contributed!
Mark the message as the answer
Unpin discussion from the Release Announcement Category
Also send an email to the theia-dev mailing List:
Subject:
Eclipse Theia v{{version}} release
Body:
Hi everyone,
The Eclipse Theia v{{version}} release has been published!
See the release on GitHub for more information: https://github.com/eclipse-theia/theia/releases/tag/v{{version}}
Thank you to everyone that participated and contributed!
Close the endgame issue: use the comment below as closing comment.
Update the discussion and comment in the Release discussion that the release is completed: https://github.com/eclipse-theia/theia/discussions/{{discussionNumber}}
The [{{version}} patch release](https://github.com/eclipse-theia/theia/releases/tag/v{{version}}) has completed, thank you to everyone that participated and contributed!
Mark the message as the answer
Also send an email to the theia-dev mailing List:
Subject:
Eclipse Theia v{{version}} patch release
Body:
Hi everyone,
The Eclipse Theia v{{version}} patch release has been published!
See the release on GitHub for more information: https://github.com/eclipse-theia/theia/releases/tag/v{{version}}
Thank you to everyone that participated and contributed!
latest documentation with the GitHub Pages workflow manually using the manual_dispatch job.After each release, check the following major dependencies for version updates:
For each dependency requiring an update, create a ticket using the following template:
Title:
Update [DEPENDENCY_NAME] to version X.Y.Z
Description:
Update [DEPENDENCY_NAME] to stay up-to-date and consume (security) fixes.
- Current version: [CURRENT_VERSION]
- Target version: [TARGET_VERSION]
After updating the dependency, please [open a ticket for the Theia IDE](https://github.com/eclipse-theia/theia-ide/issues/new?template=feature_request.md) and assign the `toDoWithRelease` and `dependencies` labels.
This indicates that the update needs to be done in Theia IDE as well and ensures it will be addressed with the next release.
If certain updates need to be done together (e.g. new electron version requires newer node version) feel free to group the tickets together.
Assign the ticket to @ndoschek.
Once the ticket is created, @ndoschek will evaluate and assign it to the appropriate person for implementation.
Perform a npm upgrade on the repository after the release to update the package-lock.json. The upgrade helps to:
To perform the upgrade:
npm upgrade at the root of the repository.package.json files (root and sub-packages) to match the resolved versions in package-lock.json, especially if the upgrade required code changes. This ensures that adopters with existing lockfiles are forced to pull at least the minimum compatible version, rather than staying on an older locked version that may be incompatible with the updated code.Performing this after the release helps us to find issues with the new dependencies and gives time to perform a license check on the dependencies.
If lerna fails during publishing (e.g., socket errors), use the following commands to reset and retry:
Reset the repository:
git reset --hard
Retry publishing only the unpublished packages:
npx lerna publish from-package --no-git-reset --no-git-tag-version --no-push