From 41070aa6468aeb351667d3532db5ca733dad3448 Mon Sep 17 00:00:00 2001 From: vince-fugnitto Date: Thu, 5 Nov 2020 15:15:09 -0500 Subject: [PATCH] documentation: update 'publishing' docs The following commit updates the `publishing` doc with additional information, including a simplified approach to releases. It also adds a note regarding potentially performing a `yarn upgrade` after releases. Signed-off-by: vince-fugnitto --- doc/Publishing.md | 143 ++++++++++++++++++++-------------------------- 1 file changed, 61 insertions(+), 82 deletions(-) diff --git a/doc/Publishing.md b/doc/Publishing.md index d78a8d279050e..e03f10dc47fbf 100644 --- a/doc/Publishing.md +++ b/doc/Publishing.md @@ -1,49 +1,27 @@ # Publishing -In order to release one should: -- update the release page (Pre-release) -- announce upcoming release -- pre-publishing steps -- login to the npm registry -- publish packages -- commit updated versions -- reset local HEAD to match release commit -- tag the published version -- announce release is done -- update the release page (Post-release) +## Release Procedure -## Updating the release page on Eclipse Foundation (Pre-release) +- [**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](#yarn-upgrade) -`One week` before the release, the project's release page should be updated in order to announce upcoming changes. -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 +## Announce Release - Create a new version - - Name: enter the new version for this release. (ex: 1.2.0). - - Date: enter the date for this 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/). - 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" +Here is an [example](https://community.theia-ide.org/t/0-11-0-release/373). -- 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. - -## Announce upcoming 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`. Here is an [example](https://community.theia-ide.org/t/0-11-0-release/373). - ## 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. @@ -54,17 +32,19 @@ One easy way is to use the theia-apps repo CI: - Go in the theia-apps repo [here](https://github.com/theia-ide/theia-apps/commits/master) and identify the latest commit. There should be an icon next to it; either a red X or a green checkmark. Click on it to go the Travis page. There re-trigger the build. We need to make sure that at least the various "next" builds pass CI.If it doesn't, it needs to be fixed before continuing. -- in case the theia-app images fail CI for reasons not related to the `next` Theia platform extensions (e.g. none of the images currently pass CI including `latest`), a fallback alternative is to build and briefly test one Theia app locally using the `next` version of a good subset of the platform extensions. +- In case the theia-app images fail CI for reasons not related to the `next` Theia platform extensions (e.g. none of the images currently pass CI including `latest`), a fallback alternative is to build and briefly test one Theia app locally using the `next` version of a good subset of the platform extensions. - Update the forum release post to ask committers to hold-off merging any PR while the release is ongoing. -## Login to the npm registry + +## Login to NPM Registry Follow this [instruction](https://docs.npmjs.com/cli/adduser) to login to the npm registry with a user account. If you don't have an account contact [Theia organization](https://www.npmjs.com/~theia) to request one. -## Publishing packages + +## Publish Packages yarn run publish @@ -72,9 +52,10 @@ This command will rebuild all packages, test them, publish to npm and bump versi If publishing of an individual package failed then publish it with `npm publish` from its root after resolving outstanding issues. -## Commit updated versions - git add * +## Commit Updated Version + + git add * git commit -m "publish v${published.version}" -s git push ${remote for main Theia repo} master:${branch} @@ -88,43 +69,18 @@ For example, if you picked `0.1.0` as a version and your git remote for the main 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. -## Reset local HEAD to match release commit - -(so that the tag we will add is attached to correct commit) - - git fetch ${remote for main Theia repo} - git reset --hard ${remote for main Theia repo}/master - -For example: - - git fetch origin - git reset --hard origin/master -## Tagging the published version +## Create Release -**Warning:** Continue only if all packages have been published successfully. Otherwise work on resolving issues and publishing failed packages. +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. - git tag v${published.version} - git push origin v${published.version} - -The version picked during package publishing should be used as `${published.version}`. - -For example, if you picked `0.1.0` as a version then you should run: - - git tag v0.1.0 - git push origin v0.1.0 - -To confirm that the tagging was correctly done, check the repo's [releases](https://github.com/eclipse-theia/theia/releases) page and confirm the release just done is listed there. - -## Create a release - -The next step of the release process is to create a new **release** on the GitHub [releases](https://github.com/eclipse-theia/theia/releases) page for the project. This will create a new release, attach the necessary assets (`.zip`, `tar.gz`, changelog link), and also notify GitHub subscribers of a new release. - -In order to create a new release on GitHub, one must: - -- navigate to the [tags](https://github.com/eclipse-theia/theia/tags) page for the project -- select the latest tag, and click `create release` from the 'more' (`...`) toolbar item -- update the release description to include a reference to the `changelog` at the respective `sha` and release version: +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: ```md [Release Changelog](https://github.com/eclipse-theia/theia/blob/${sha}/CHANGELOG.md#${changelog-version-header}) @@ -136,26 +92,49 @@ In order to create a new release on GitHub, one must: [Release Changelog](https://github.com/eclipse-theia/theia/blob/2aa2fa1ab091ec36ef851c4e364b322301cddb40/CHANGELOG.md#v120) ``` -- select `create release` at the bottom of the page +- 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). -## Updating the release page on Eclipse Foundation (Post-release) -- Login to [Eclipse Foundation Theia project page]( https://projects.eclipse.org/projects/ecd.theia) -- Select the edit tab from the current 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 new changelog.md. + - Paste the content of the changelog.md. - Compatibility section - Paste the content of the "Breaking changes" + - 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. -## Announce release is done -- Update the forum release post to announce that the release is done. +## Post Release + +### Announce Release is Completed + +Update the forum release post to announce that the release has completed. + + +### Yarn Upgrade + +After a release, 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.