Skip to content

Commit d8f7729

Browse files
vince-fugnittovince-fugnitto
authoredAug 22, 2023
docs: update publishing documentation (#12817)
The commit updates the `publishing` documentation with the latest information, and lerna workarounds. Signed-off-by: vince-fugnitto <vincent.fugnitto@ericsson.com>
·
v1.59.0v1.41.0
1 parent 3a49fca commit d8f7729

File tree

1 file changed

+108
-124
lines changed

1 file changed

+108
-124
lines changed
 

‎doc/Publishing.md

+108-124
Original file line numberDiff line numberDiff line change
@@ -1,166 +1,150 @@
11
# Publishing
22

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

45
## Release Procedure
56

6-
- [**Yarn Upgrade**](#yarn-upgrade)
7-
- [**Announce Release**](#announce-release)
8-
- [**Pre-Publishing Steps**](#pre-publishing-steps)
9-
- [**Login to NPM Registry**](#login-to-npm-registry)
10-
- [**Publish Packages**](#publish-packages)
11-
- [**Commit Updated Versions**](#commit-updated-version)
12-
- [**Create Release**](#create-release)
13-
- [**Update Eclipse Release Page**](#update-eclipse-release-page)
14-
- [**Post-Release**](#post-release)
15-
- [Announce Release is Completed](#announce-release-is-completed)
16-
17-
## Yarn Upgrade
18-
19-
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`.
20-
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.
21-
22-
To successfully complete a `yarn upgrade`, one must:
23-
- Perform `yarn upgrade` at the root of the repository.
24-
- Fix any compilation errors, typing issues, and failing tests that may be introduced.
25-
26-
## Announce Release
27-
28-
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/).
29-
30-
Here is an [example](https://community.theia-ide.org/t/0-11-0-release/373).
31-
7+
- [**Pre-Release Steps**](#pre-release-steps)
8+
- [Yarn Upgrade](#yarn-upgrade)
9+
- [Announce Release](#announce-release)
10+
- [Localization](#localization)
11+
- [Changelog](#changelog)
12+
- [Update Milestone](#update-milestone)
13+
- [**Release**](#publishing)
14+
- [Community Releases](#community-releases)
15+
- [**Post-Release Steps**](#post-release-steps)
16+
- [Eclipse Release](#eclipse-release)
17+
- [Announce Release is Completed](#announce-release-is-completed)
18+
- [Update Future Milestones](#update-future-milestones)
19+
- [Publish GitHub Pages](#publish-github-pages)
20+
- [**Troubleshooting**](#troubleshooting)
21+
- [**Failures During Publishing**](#failures-during-publishing)
3222

3323
## Pre-Release Steps
3424

35-
- Ensure that the [changelog](https://github.com/eclipse-theia/theia/blob/master/CHANGELOG.md) is updated and merged for the release.
36-
- The `changelog` should reflect updates included in the release:
37-
- Notable features, improvements and bug fixes.
38-
- Any possible breaking changes.
39-
- The `changelog` should follow the format of previous releases:
40-
- Include the version, and date.
41-
- Include a link to the appropriate milestone.
42-
- Include all breaking changes in a separate section.
43-
- Prefix entries by their most appropriate extension name (ex: `[core]`).
44-
- Entries should include a link to their corresponding pull-request.
45-
- Entries should be in alphabetical order.
46-
- Entries should be in the past tense (ex: 'Added support...').
47-
- Ensure that merged pull-requests for the given release are added to the corresponding release [milestone](https://github.com/eclipse-theia/theia/milestones):
48-
- 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.
49-
- Run the [automatic translation workflow](https://github.com/eclipse-theia/theia/actions/workflows/translation.yml) and merge the created pull request if necessary.
50-
51-
52-
## Pre-Publishing Steps
53-
54-
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.
55-
56-
- Update the forum release post to ask committers to hold-off merging any PR while the release is ongoing.
57-
58-
59-
## Login to NPM Registry
25+
### Yarn Upgrade
6026

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

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

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

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

68-
yarn run publish
40+
### Announce Release
6941

70-
This command will rebuild all packages, test them, publish to npm and bump versions.
42+
It is a good idea to give a heads-up to developers and the community some hours before a release.
43+
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).
7144

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

47+
The localization (`nls`) updates should be performed before a release ([example](https://github.com/eclipse-theia/theia/pull/12665)).
48+
To help we have an [automatic translation](https://github.com/eclipse-theia/theia/actions/workflows/translation.yml) workflow which can be triggered.
49+
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.
7450

75-
## Commit Updated Version
51+
### Changelog
7652

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

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

83-
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:
59+
The `changelog` should follow the same format as previous releases:
8460

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

89-
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.
70+
### Update Milestone
9071

72+
The given release [milestone](https://github.com/eclipse-theia/theia/milestones) should be updated to include all commits that composed the release.
73+
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.
9174

92-
## Create Release
75+
## Release
9376

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

97-
In order to create a new release, one must:
98-
- Navigate to the releases [page](https://github.com/eclipse-theia/theia/releases).
99-
- Select the _"Draft a new release"_ button.
100-
- Input the appropriate release `tag` version (ex: `v1.2.0`).
101-
- Input the appropriate release `name` (ex: `Eclipse Theia v1.2.0`).
102-
- Include a release `description` to include a reference to the `changelog` at the respective `sha` and release version:
79+
- Checkout `master` with the latest changes (`git pull` to pull the latest changes).
80+
- Confirm the latest changes are present (`git log`).
81+
- Build the changes (`yarn`).
82+
- Confirm the changes are built (individual `@theia` extensions should have their `lib/` folders present).
83+
- Perform the release using `yarn publish:latest` - choose an appropriate version.
84+
- Keep the `packages/core/README.md` updates in a separate commit ([example](https://github.com/eclipse-theia/theia/commit/21fa2ec688e4a8bcf10203d6dc0f730af43a7f58)).
85+
- Prepare a release - create a branch with the pattern `release/x.y.z` (ex: `release/1.40.x`).
86+
- Once approved, merge using `Rebase and Merge` (**DO NOT `Squash and Merge`**).
87+
- Once the pull-request is merged, pull the changes locally and tag the publishing commit (ex: `git tag -a "${version} ${sha} -m "${version}"`).
88+
- Publish the tag to GitHub.
89+
- Create a GitHub release:
90+
- Navigate to the releases [page](https://github.com/eclipse-theia/theia/releases).
91+
- Select the _"Draft a new release"_ button.
92+
- Input the appropriate release `tag` version (ex: `v1.2.0`).
93+
- Input the appropriate release `name` (ex: `Eclipse Theia v1.2.0`).
94+
- Use the `generate release notes` button to generate the list of contributors (including new ones), and format them similarly to other releases.
95+
- Include a release `description` to include a reference to the `changelog` at the respective `sha` and release version.
96+
- Include a reference to the migration guide in the release description.
97+
- Select _"Publish Release"_ bottom at the bottom of the page.
98+
- 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).
10399

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

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

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

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

116-
```md
117-
[Migration Guide](https://github.com/eclipse-theia/theia/blob/master/doc/Migration.md)
118-
```
111+
### Eclipse Release
119112

120-
- Select _"Publish Release"_ bottom at the bottom of the page.
121-
122-
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).
123-
124-
125-
## Update Eclipse Release Page
126-
127-
Login to [Eclipse Foundation Theia project page]( https://projects.eclipse.org/projects/ecd.theia)
128-
- On the right side panel, select Release / Create a new release
129-
130-
Create a new version
131-
- Name: enter the new version for this release. (ex: 1.2.0).
132-
- Date: enter the date for this release.
133-
134-
Select the edit tab
135-
- In "The Basic" section
136-
- Select the "Type A" in the IP Due Diligence type.
137-
- In the "Project Plan"
138-
- Deliverables section
139-
- Paste the content of the changelog.md.
140-
- Compatibility section
141-
- Paste the content of the "Breaking changes"
113+
- Login to [Eclipse Foundation Theia project page]( https://projects.eclipse.org/projects/ecd.theia)
114+
- On the right side menu, select `Release` / `Create a new release`
115+
- `Release Date`: enter the date for the release.
116+
- `Name`: enter the version of the release (ex: `1.40.0`).
117+
- Select `Create and edit`.
118+
- In the `projects` section:
119+
- Add the changelog link to `deliverables`.
120+
- Add the breaking changes link to `compatibility`.
121+
- Save the changes.
122+
- To confirm the release is successful:
123+
- Open the [project page](https://projects.eclipse.org/projects/ecd.theia)
124+
- Select the version you just created.
125+
- Open the Review plan section, you should see the data provided before.
142126

127+
### Announce Release is Completed
143128

144-
- When completing the edition, select "Save" at the bottom of the page.
145-
- To confirm the release is successful,
146-
- Open the page https://projects.eclipse.org/projects/ecd.theia
147-
- Select the version you just created.
148-
- Open the Review plan section, you should see the data provided before.
129+
- Update the forum release post to announce that the release has completed.
130+
- 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).
149131

132+
### Update Future Milestones
150133

151-
## Post Release
134+
- Close current release [milestone](https://github.com/eclipse-theia/theia/milestones).
135+
- 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.).
152136

153-
### Announce Release is Completed
137+
### Publish GitHub Pages
154138

155-
- Update the forum release post to announce that the release has completed.
156-
- 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).
139+
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.
157140

158-
### Update Milestones
141+
## Troubleshooting
159142

160-
* Close current release [milestone](https://github.com/eclipse-theia/theia/milestones).
161-
* 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.).
143+
### Failures During Publishing
162144

163-
### Update Roadmap
145+
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
146+
packages using a workaround command:
164147

165-
* 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).
166-
* 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.
148+
```bash
149+
npx lerna publish from-package --no-git-reset --no-git-tag-version --no-push
150+
```

0 commit comments

Comments
 (0)
Please sign in to comment.