Skip to content

Release model docs for the ecosystem updated #6646

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

Merged
merged 1 commit into from
Jun 10, 2019
Merged

Release model docs for the ecosystem updated #6646

Show file tree
Hide file tree
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
55 changes: 55 additions & 0 deletions docs/docs/contributing/checklist.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# #!/usr/bin/env bash
stable=$1

rc="$(($stable+1))"
next="$(($rc+1))"

stable_version="0.$stable.0"
rc_version="0.$rc.0-RC1"
next_version="0.$next.0"
stable_branch="0.$stable.x"
rc_branch="0.$rc.x"

LIST='- [ ] Publish artifacts to Maven via CI
- [ ] On branch `<stable-branch>`, set `baseVersion` to `<stable-version>` and `git tag` it as `<stable-version>`. This will publish artefacts to Sonatype and GitHub Release
- [ ] Merge branch `<stable-branch>` into `master` to guarantee that all of the `<stable-branch>` commits are propagated to `master`
- [ ] Look at the milestone of the RC version being released. Move all the open issues from it to the next milestone.
- [ ] Create branch `<rc-branch>` from `master`
- [ ] On `<rc-branch>`, set `baseVersion` to `<rc-version>` and `git tag` it as `<rc-version>`. This will publish artefacts to Sonatype and GitHub Release.
- [ ] On `master`, set `baseVersion` to `<next-version>`
- [ ] Update `scalaVersion` (and, if applicable, the `sbt-dotty` version) in the Dotty ecosystem projects
- [ ] https://github.com/lampepfl/dotty-example-project
- [ ] https://github.com/lampepfl/dotty-example-project/tree/mill
- [ ] https://github.com/lampepfl/dotty.g8 [![Build Status](https://travis-ci.org/lampepfl/dotty.g8.svg?branch=master)](https://travis-ci.org/lampepfl/dotty.g8/)
- [ ] Committed to `master`
- [ ] https://github.com/lampepfl/dotty-cross.g8 [![Build Status](https://travis-ci.org/lampepfl/dotty-cross.g8.svg?branch=master)](https://travis-ci.org/lampepfl/dotty-cross.g8/)
- [ ] Committed to `master`
- [ ] https://github.com/lampepfl/homebrew-brew [![Build Status](https://travis-ci.org/lampepfl/homebrew-brew.svg?branch=master)](https://travis-ci.org/lampepfl/homebrew-brew)
- [ ] Committed to `master`
- SHA256 sum for the artifact: `wget -q -O- https://github.com/lampepfl/dotty/releases/download/<rc-version>/sha256sum.txt | grep ".tar.gz"`
- [ ] https://github.com/lampepfl/packtest [![Build Status](https://travis-ci.org/lampepfl/packtest.svg?branch=master)](https://travis-ci.org/lampepfl/packtest)
- [ ] Committed to `master`
- [ ] https://github.com/scalacenter/scastie
- [ ] PR submitted
- [ ] PR merged
- [ ] https://scastie.scala-lang.org/ -> Build Settings -> Dotty mentions `<rc-version>`
- [ ] Dotty reference compiler [![Build Status](http://dotty-ci.epfl.ch/api/badges/lampepfl/dotty/status.svg)](http://dotty-ci.epfl.ch/lampepfl/dotty)
- [ ] PR submitted
- [ ] PR merged
- [ ] Scalac [![Build Status](https://travis-ci.org/scala/scala.svg?branch=2.13.x)](https://travis-ci.org/scala/scala)
- [ ] PR submitted
- [ ] PR merged
- [ ] Announce the release
- [ ] Publish releases for the RC and stable versions on GitHub Releases
- [ ] Publish Blog Post on dotty.epfl.ch
- [ ] Make an announcement thread on https://contributors.scala-lang.org
- [ ] Tweet the announcement blog post on https://twitter.com/scala_lang

[Instructions on how to release](https://dotty.epfl.ch/docs/contributing/release.html)'

echo "$LIST" |\
sed "s/<stable-version>/$stable_version/g" |\
sed "s/<rc-version>/$rc_version/g" |\
sed "s/<next-version>/$next_version/g" |\
sed "s/<stable-branch>/$stable_branch/g" |\
sed "s/<rc-branch>/$rc_branch/g"
87 changes: 52 additions & 35 deletions docs/docs/contributing/release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,42 +32,35 @@ CI is set to automatically detect the tags of the format discussed above and per

The CI operation is entirely automatic provided you have tagged the release correctly. No need to do anything here.

### Canceling CI builds
**The below guidelines are needed only to speed up things. It is no mistake if you skip this section. However, if you do things wrong here, there may be trouble. So do it only if you feel yourself confident with the release cycle and the workings of the CI.**

Note that after the first stage of the release cycle (see "Publishing artifacts to Maven via CI" section of the checklist below) only three test runs are required to be run at the CI:

- `master` branch's latest *commit* with the updated `baseVersion`
- `<stable-version>` *tag* of the stable version being released
- `<rc-version>` *tag* of the RC version being released

However you may end up with as many as 6 tasks being run. The auxiliary tasks may include:

- *commit* tests of the *tags* specified above. You may have two of these, corresponding to the two tags. You should see them appearing to have the same commit hash in the CI, but one of them will have the tag next to it and the other one will not. The *tag* one must remain, as the CI tasks on tags publish to maven. CI tasks on commits do not. So it is safe to cancel the task running on the commit, if the commit hash is the same as that of the tag's task commit.
- Older commit from the `master` branch. Look for all the tasks run on the `master` branch in the CI and see if there are more than one of these. Then, find the one testing the most recent commit of the branch. The others can safely be canceled.

## Documentation
### Release Procedure Checklist
Before we start the release procedure, we create an issue with a release checklist. As we go through the release, we update the checklist. In the checklist template below, the following variables are used:

- `<stable-version>` is the stable version being released, e.g. `0.14.0`. It is identical to the git tag under which it is released.
- `<rc-version>` is the version of the RC version being released, e.g. `0.15.0-RC1`. It is identical to the git tag under which it is released.
- `<stable-branch>` is the name of the stable branch being released, e.g. `0.14.x` if we are releasing `0.14.0`
- `<rc-branch>` is the RC's branch. E.g. if we are releasing `0.14.0` and `0.15.0-RC1`, the RC version is `0.15.0-RC1`, and `<rc-branch>` is `0.15.x`.
- `<next-version>` is the tech preview version. It is the next version after the currently released RC. E.g. if we are releasing `0.15.0-RC1`, this variable will be `0.16.0`.

A good workflow is to compute these variables before each release, then replace them in the checklist below:

```
- [ ] Publish artifacts to Maven via CI
- [ ] On branch`<stable-branch>`, set `baseVersion` to `<stable-version>` and `git tag` it as `<stable-version>`. This will publish artefacts to Sonatype and GitHub Release
- [ ] Merge branch `<stable-branch>` into `master` to guarantee that all of the `<stable-branch>` commits are propagated to `master`
- [ ] Look at the milestone of the RC version being released. Move all the open issues from it to the next milestone.
- [ ] Create branch `<rc-branch>` from `master`
- [ ] On `<rc-branch>`, set `baseVersion` to `<rc-version>` and `git tag` it as `<rc-version>`. This will publish artefacts to Sonatype and GitHub Release.
- [ ] On `master`, set `baseVersion` to `<next-version>`
- [ ] Update `scalaVersion` (and, if applicable, the `sbt-dotty` version) in the Dotty ecosystem projects
- [ ] https://github.com/lampepfl/dotty-example-project
- [ ] https://github.com/lampepfl/dotty-example-project/tree/mill
- [ ] https://github.com/lampepfl/dotty.g8
- [ ] https://github.com/lampepfl/dotty-cross.g8
- [ ] https://github.com/lampepfl/homebrew-brew
- [ ] https://github.com/lampepfl/packtest
- [ ] https://github.com/scalacenter/scastie
- [ ] Dotty itself – update the `referenceVersion` in the `master` branch to `<rc-version>`. This is the version of Dotty used to compile the Dotty codebase on `master`.
- [ ] Scalac CI, like this: scala/scala#7993
- [ ] Announce the release
- [ ] Publish releases for the RC and stable versions on GitHub Releases
- [ ] Publish Blog Post on dotty.epfl.ch
- [ ] Make an announcement thread on https://contributors.scala-lang.org
- [ ] Tweet the announcement blog post on https://twitter.com/scala_lang
```
Before we start the release procedure, we create an issue with a release checklist. As we go through the release, we update the checklist. To generate the checklist, run the following command:

`bash <(curl -sL https://raw.githubusercontent.com/lampepfl/dotty/master/docs/docs/contributing/checklist.sh) <stable_release>`

Above, `<stable_release>` is the stable version being released. For example, if you are releasing `0.14.0` and `0.15.0-RC1`, this variable is `14` and the command is as follows:

`bash <(curl -sL https://raw.githubusercontent.com/lampepfl/dotty/master/docs/docs/contributing/checklist.sh) 14`

Copy and paste the output into the release issue.

The ecosystem update section for some projects also mentions a set of criteria upon which the project is to be marked in the checklist. When the Travis build status is specified next to the project's name, it is to be understood that this build must pass after all of the other criteria of that project are checked. Note that due to caching, the label image next to the link may not reflect the real status of the build. Therefore, to verify the status, click on the link and make sure that your recent commit passes.

When no criteria is specified, common sense is to be used.

### GitHub Releases and Blog Post
After the release is done, we document it as follows:
Expand All @@ -79,12 +72,36 @@ After the release is done, we document it as follows:
After releasing a new version of Dotty, we need to make sure to update the following related projects:

- [Example Project](https://github.com/lampepfl/dotty-example-project)
- To deploy locally: `git clone https://github.com/lampepfl/dotty-example-project.git && cd dotty-example-project/`
- To test locally: `sbt run`
- [Commit](https://github.com/lampepfl/dotty-example-project/commit/76bf0b4d708206b1901fa7f291f07cd470506e79) updating the Dotty version (only `README` and `build.sbt` files)
- [Example Project with Mill](https://github.com/lampepfl/dotty-example-project/tree/mill)
- Deploy: `git clone https://github.com/lampepfl/dotty-example-project && cd dotty-example-project && git checkout mill`
- Test: `mill root.run`
- [Commit 1](https://github.com/lampepfl/dotty-example-project/commit/e1ad1905ef38d07943e0c176333ba24e306a2078) – `build.sc` only; [Commit 2](https://github.com/lampepfl/dotty-example-project/commit/23bc5df89e72b782ab8e19157d6bbcb67eef30cd)
- [Dotty G8 template](https://github.com/lampepfl/dotty.g8)
- Deploy: `git clone https://github.com/lampepfl/dotty.g8.git`
- Test (note the relative path as argument to `sbt new`, hence this command should be run after Deploy in the same directory as Deploy): `sbt new file://./dotty.g8 --name=foo --description=bar && cd foo && sbt run`
- [Commit](https://github.com/lampepfl/dotty.g8/commit/0cde8fa843e15e916f07f22a196f35a5988b26af)
- [Dotty G8 template with cross build support](https://github.com/lampepfl/dotty-cross.g8)
- Deploy: `git clone https://github.com/lampepfl/dotty-cross.g8.git`
- Test: `sbt new file://./dotty-cross.g8 --name=foo --description=bar && cd foo && sbt run`
- [Commit](https://github.com/lampepfl/dotty-cross.g8/commit/0e3ea2ae8ba8d001e63e5098ff60d728036d358f)
- [Dotty Homebrew Formula](https://github.com/lampepfl/homebrew-brew)
- Deploy: `git clone https://github.com/lampepfl/homebrew-brew.git && cd homebrew-brew`
- [Commit](https://github.com/lampepfl/homebrew-brew/commit/04f7284564387754a360a354159f2f8d6156a6c7). SHA256 sum comes from the issue checklist computed for the release as specified above. The file with checksums is available at [GitHub Releases](https://github.com/lampepfl/dotty/releases) -> release in question -> assets -> `sha256sum.txt` -> `*.tar.gz` file sum.
- [Dotty test under various OSs](https://github.com/lampepfl/packtest)
- 🚫[Scastie](https://github.com/scalacenter/scastie/) – FTTB doesn't work with the new Dotty releases because Scastie uses sbt 0.13.
- Deploy: `git clone https://github.com/lampepfl/packtest.git && cd packtest`
- [Commit](https://github.com/lampepfl/packtest/commit/6d3edf7333e0e788af7c4f4ab976b56905ddf9ed)
- [Scastie](https://github.com/scalacenter/scastie/)
- Deploy (copy-paste the command and append the release id, e.g. `15` for `0.15.0-RC1`): `git clone https://github.com/scalacenter/scastie.git && cd scastie && git remote add staging https://github.com/dotty-staging/scastie && git checkout -b dotty-release-`<release_id>
- [PR](https://github.com/scalacenter/scastie/pull/433) – push your changes to `staging` repo (as defined in "Deploy" above) with `git push -u staging`, then submit the PR from there.
- [Dotty](https://github.com/lampepfl/dotty/)
- If you are reading this, Dotty should already be deployed on your machine :)
- [PR](https://github.com/lampepfl/dotty/pull/6557)
- [Scalac](https://github.com/scala/scala)
- Deploy: `git clone https://github.com/scala/scala.git && cd scala && git remote add staging https://github.com/dotty-staging/scala && git checkout -b dotty-release-`<release_id>
- [PR](https://github.com/scala/scala/pull/7993)

For each need to do the following:

Expand Down