Skip to content

Commit

Permalink
documentation: update 'publishing' docs
Browse files Browse the repository at this point in the history 
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 <vincent.fugnitto@ericsson.com>
  • Loading branch information
@vince-fugnitto
vince-fugnitto committed Nov 10, 2020
1 parent 4314838 commit 41070aa
Showing 1 changed file with 61 additions and 82 deletions.
143 changes: 61 additions & 82 deletions doc/Publishing.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -54,27 +32,30 @@ 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

This command will rebuild all packages, test them, publish to npm and bump versions.

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}

Expand All @@ -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})
Expand All @@ -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.

0 comments on commit 41070aa

Please sign in to comment.