Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update publishing documentation #12817

Merged
merged 1 commit into from
Aug 22, 2023
Merged

docs: update publishing documentation #12817

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
232 changes: 108 additions & 124 deletions doc/Publishing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,166 +1,150 @@
# Publishing

The documentation describes the various steps and information regarding the release of Eclipse Theia for maintainers.

## Release Procedure

- [**Yarn Upgrade**](#yarn-upgrade)
- [**Announce Release**](#announce-release)
- [**Pre-Publishing Steps**](#pre-publishing-steps)
- [**Login to NPM Registry**](#login-to-npm-registry)
- [**Publish Packages**](#publish-packages)
- [**Commit Updated Versions**](#commit-updated-version)
- [**Create Release**](#create-release)
- [**Update Eclipse Release Page**](#update-eclipse-release-page)
- [**Post-Release**](#post-release)
- [Announce Release is Completed](#announce-release-is-completed)

## Yarn Upgrade

Before a release (Monday of the same week), it is a good time to perform a `yarn upgrade` on the repository to update the `yarn.lock`.
Updating the `yarn.lock` helps identify potential problems with our dependency version ranges, and is more representative of what downstream adopters may pull when building their own applications.

To successfully complete a `yarn upgrade`, one must:
- Perform `yarn upgrade` at the root of the repository.
- Fix any compilation errors, typing issues, and failing tests that may be introduced.

## Announce Release

It's good to give a heads-up to the Theia developers some hours before a release. One can use whatever forum is appropriate. At the time of writing this is [`Discourse`](https://community.theia-ide.org/).

Here is an [example](https://community.theia-ide.org/t/0-11-0-release/373).

- [**Pre-Release Steps**](#pre-release-steps)
- [Yarn Upgrade](#yarn-upgrade)
- [Announce Release](#announce-release)
- [Localization](#localization)
- [Changelog](#changelog)
- [Update Milestone](#update-milestone)
- [**Release**](#publishing)
- [Community Releases](#community-releases)
- [**Post-Release Steps**](#post-release-steps)
- [Eclipse Release](#eclipse-release)
- [Announce Release is Completed](#announce-release-is-completed)
- [Update Future Milestones](#update-future-milestones)
- [Publish GitHub Pages](#publish-github-pages)
- [**Troubleshooting**](#troubleshooting)
- [**Failures During Publishing**](#failures-during-publishing)

## Pre-Release Steps

- Ensure that the [changelog](https://github.com/eclipse-theia/theia/blob/master/CHANGELOG.md) is updated and merged for the release.
- The `changelog` should reflect updates included in the release:
- Notable features, improvements and bug fixes.
- Any possible breaking changes.
- The `changelog` should follow the format of previous releases:
- Include the version, and date.
- Include a link to the appropriate milestone.
- Include all breaking changes in a separate section.
- Prefix entries by their most appropriate extension name (ex: `[core]`).
- Entries should include a link to their corresponding pull-request.
- Entries should be in alphabetical order.
- Entries should be in the past tense (ex: 'Added support...').
- Ensure that merged pull-requests for the given release are added to the corresponding release [milestone](https://github.com/eclipse-theia/theia/milestones):
- Generally, milestones are automatically added on merge however not for forks. It is therefore important to manually add such contributions to the milestone for the time being.
- Run the [automatic translation workflow](https://github.com/eclipse-theia/theia/actions/workflows/translation.yml) and merge the created pull request if necessary.


## Pre-Publishing Steps

Before publishing, it's important to make sure that a functional Theia application can be made from the latest `next` version of the platform. Else we will have problems with "latest" after publishing.

- Update the forum release post to ask committers to hold-off merging any PR while the release is ongoing.


## Login to NPM Registry
### Yarn Upgrade

Follow this [instruction](https://docs.npmjs.com/cli/adduser) to login to the npm registry with a user account.
In general, it is recommended to perform a `yarn upgrade` on the repository prior to a release to update the `yarn.lock`.
The upgrade helps to:

If you don't have an account contact [Theia organization](https://www.npmjs.com/~theia) to request one.
- Better represents what adopters will pull during a release.
- Validate dependencies with our declared version ranges.
- Fix known security vulnerabilities from dependencies.

In order to successfully perform a `yarn upgrade` one must:

## Publish Packages
- Perform a `yarn upgrade` at the root of the repository.
- Fix any potential compilation errors, typing errors, and failing tests that may have been introduced.
- Confirm licenses and wait for the "IP Check" to complete ([example](https://gitlab.eclipse.org/eclipsefdn/emo-team/iplab/-/issues/9377)).

yarn run publish
### Announce Release

This command will rebuild all packages, test them, publish to npm and bump versions.
It is a good idea to give a heads-up to developers and the community some hours before a release.
At the time of writing this is [Discourse](https://community.theia-ide.org/). Here is an [example](https://community.theia-ide.org/t/eclipse-theia-v1-40-0-release/3112/5).

If publishing of an individual package failed then publish it with `npm publish` from its root after resolving outstanding issues.
### Localization

The localization (`nls`) updates should be performed before a release ([example](https://github.com/eclipse-theia/theia/pull/12665)).
To help we have an [automatic translation](https://github.com/eclipse-theia/theia/actions/workflows/translation.yml) workflow which can be triggered.
Note that due to the required CI check (`lint`) we will need for force-push the branch that the bot creates to properly trigger CI.

## Commit Updated Version
### Changelog

git add *
git commit -m "publish v${published.version}" -s
git push ${remote for main Theia repo} master:${branch}
The [changelog](https://github.com/eclipse-theia/theia/blob/master/CHANGELOG.md) should be updated and merged for the release.
The updates should document the release as thoroughly as possible:

The version picked during package publishing should be used as `${published.version}`.
- Notable new features, improvements and bug fixes.
- Potential breaking changes.

For example, if you picked `0.1.0` as a version and your git remote for the main Theia repo is named `origin`, then you should run:
The `changelog` should follow the same format as previous releases:

git add *
git commit -m "publish v0.1.0" -s
git push origin master:release_0_1_0
- Include the version, and date.
- Add a link to the appropriate milestone.
- Document all breaking changes in a separate section.
- Entries should be formatted in the following way:
- Prefix by their most appropriate extension name (ex: `[core]`).
- Add a link to their corresponding pull-request.
- Should be in alphabetical order.
- Should be in the past tense (ex: 'Added support...').

Then from the project's [main page](https://github.com/eclipse-theia/theia), create a pull request from the branch just pushed. Have another committer on standby to quickly review and approve the PR, then merge it.
### Update Milestone

The given release [milestone](https://github.com/eclipse-theia/theia/milestones) should be updated to include all commits that composed the release.
Generally, milestones are automatically added on merge but not necessarily for forks. It is therefore important to manually add such contributions to the milestone for the time being.

## Create Release
## Release

The next step is to create a new [**Release**](https://github.com/eclipse-theia/theia/releases).
This will create a new `tag`, `release` with the appropriate assets (`.zip`, `tar.gz`) and notify subscribers.
The release instructions are as follows:

In order to create a new release, one must:
- Navigate to the releases [page](https://github.com/eclipse-theia/theia/releases).
- Select the _"Draft a new release"_ button.
- Input the appropriate release `tag` version (ex: `v1.2.0`).
- Input the appropriate release `name` (ex: `Eclipse Theia v1.2.0`).
- Include a release `description` to include a reference to the `changelog` at the respective `sha` and release version:
- Checkout `master` with the latest changes (`git pull` to pull the latest changes).
- Confirm the latest changes are present (`git log`).
- Build the changes (`yarn`).
- Confirm the changes are built (individual `@theia` extensions should have their `lib/` folders present).
- Perform the release using `yarn publish:latest` - choose an appropriate version.
- Keep the `packages/core/README.md` updates in a separate commit ([example](https://github.com/eclipse-theia/theia/commit/21fa2ec688e4a8bcf10203d6dc0f730af43a7f58)).
- Prepare a release - create a branch with the pattern `release/x.y.z` (ex: `release/1.40.x`).
- Once approved, merge using `Rebase and Merge` (**DO NOT `Squash and Merge`**).
- Once the pull-request is merged, pull the changes locally and tag the publishing commit (ex: `git tag -a "${version} ${sha} -m "${version}"`).
- Publish the tag to GitHub.
- Create a GitHub release:
- Navigate to the releases [page](https://github.com/eclipse-theia/theia/releases).
- Select the _"Draft a new release"_ button.
- Input the appropriate release `tag` version (ex: `v1.2.0`).
- Input the appropriate release `name` (ex: `Eclipse Theia v1.2.0`).
- Use the `generate release notes` button to generate the list of contributors (including new ones), and format them similarly to other releases.
- Include a release `description` to include a reference to the `changelog` at the respective `sha` and release version.
- Include a reference to the migration guide in the release description.
- Select _"Publish Release"_ bottom at the bottom of the page.
- For additional information, please consult the official GitHub documentation regarding [creating releases](https://help.github.com/en/github/administering-a-repository/managing-releases-in-a-repository#creating-a-release).

```md
[Release Changelog](https://github.com/eclipse-theia/theia/blob/${sha}/CHANGELOG.md#${changelog-version-header})
```
### Community Releases

For example (version `v1.2.0`):
For the most part community releases are similar to regular releases but with fewer steps (ex: no need to submit a pull-request).
In order to perform a community releases we want to:

```md
[Release Changelog](https://github.com/eclipse-theia/theia/blob/2aa2fa1ab091ec36ef851c4e364b322301cddb40/CHANGELOG.md#v120)
```
- Prepare the community release branch which branches off from a specific release `tag`.
- Cherry-pick any changes we want to apply on top of the `tag` (ex: patches that fix regressions, security vulnerabilities).
- Perform the release as usual (we want to use a `dist-tag` of `community`).

- Include a reference to the migration guide in the release description:
## Post-Release Steps

```md
[Migration Guide](https://github.com/eclipse-theia/theia/blob/master/doc/Migration.md)
```
### Eclipse Release

- Select _"Publish Release"_ bottom at the bottom of the page.

For additional information, please consult the official GitHub documentation regarding [creating releases](https://help.github.com/en/github/administering-a-repository/managing-releases-in-a-repository#creating-a-release).


## Update Eclipse Release Page

Login to [Eclipse Foundation Theia project page]( https://projects.eclipse.org/projects/ecd.theia)
- On the right side panel, select Release / Create a new release

Create a new version
- Name: enter the new version for this release. (ex: 1.2.0).
- Date: enter the date for this release.

Select the edit tab
- In "The Basic" section
- Select the "Type A" in the IP Due Diligence type.
- In the "Project Plan"
- Deliverables section
- Paste the content of the changelog.md.
- Compatibility section
- Paste the content of the "Breaking changes"
- Login to [Eclipse Foundation Theia project page]( https://projects.eclipse.org/projects/ecd.theia)
- On the right side menu, select `Release` / `Create a new release`
- `Release Date`: enter the date for the release.
- `Name`: enter the version of the release (ex: `1.40.0`).
- Select `Create and edit`.
- In the `projects` section:
- Add the changelog link to `deliverables`.
- Add the breaking changes link to `compatibility`.
- Save the changes.
- To confirm the release is successful:
- Open the [project page](https://projects.eclipse.org/projects/ecd.theia)
- Select the version you just created.
- Open the Review plan section, you should see the data provided before.

### Announce Release is Completed

- When completing the edition, select "Save" at the bottom of the page.
- To confirm the release is successful,
- Open the page https://projects.eclipse.org/projects/ecd.theia
- Select the version you just created.
- Open the Review plan section, you should see the data provided before.
- Update the forum release post to announce that the release has completed.
- Submit to "Theia News", so that a Tweet will be created by the Twitter managers. Use [this template](https://github.com/eclipse-theia/theia/wiki/Eclipse-Theia-Twitter-strategy#release-announcement-no-review) for the message and post it [here](https://forms.gle/ccS6qawpS54FQZht5).

### Update Future Milestones

## Post Release
- Close current release [milestone](https://github.com/eclipse-theia/theia/milestones).
- Create the next two milestones in the case they do not already exist. Generally, the release is performed on the last Thursday of the month, but there may be exceptions (bug fix release, holidays, etc.).

### Announce Release is Completed
### Publish GitHub Pages

- Update the forum release post to announce that the release has completed.
- Submit to "Theia News", so that a Tweet will be created by the Twitter managers. Use [this template](https://github.com/eclipse-theia/theia/wiki/Eclipse-Theia-Twitter-strategy#release-announcement-no-review) for the message and post it [here](https://forms.gle/ccS6qawpS54FQZht5).
Following a release we should publish the `latest` documentation with our [GitHub Pages](https://github.com/eclipse-theia/theia/actions/workflows/publish-gh-pages.yml) workflow. The publishing should be performed manually using the `manual_dispatch` job.

### Update Milestones
## Troubleshooting

* Close current release [milestone](https://github.com/eclipse-theia/theia/milestones).
* Create the next two milestones in the case they do not already exist. Generally, the release is performed on the last Thursday of the month, but there may be exceptions (bug fix release, holidays, etc.).
### Failures During Publishing

### Update Roadmap
Sometimes `lerna` will fail during publishing (ex: socket errors). If such a case happens we should `git reset --hard` and retry publishing of only unpublished
packages using a workaround command:

* If the current release is the last in a quarter, ask the team to update the [roadmap](https://github.com/eclipse-theia/theia/wiki/Eclipse-Theia-Roadmap) of the past quarter (close, remove or move items).
* If the current release is the second in a quarter, create [roadmap template](https://github.com/eclipse-theia/theia/wiki/Eclipse-Theia-Roadmap) for the next quarter, ask the team to contribute to it and add it to the agenda of the Theia dev meeting.
```bash
npx lerna publish from-package --no-git-reset --no-git-tag-version --no-push
```