Skip to content

Describe the release procedures #562

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

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Describe the release procedures #562

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
220 changes: 220 additions & 0 deletions RELEASE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,220 @@
# kotlinx-datetime release checklist

## Full release

To release `kotlinx-datetime`:

1. Make sure there are no updates to either Windows/IANA timezone name mapping
or to the IANA timezone database that we publish.
* <https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Check_Updates>
checks this automatically every night.
* Follow the procedure in
[UPDATE_TIMEZONE_DATABASE.md](UPDATE_TIMEZONE_DATABASE.md)
if there are updates or to check for updates manually.

2. Check out the `master` branch:
> `git checkout master`

3. Retrieve the most recent version of it:
> `git pull`

4. Search & replace `<old-version>` with `<version>` in
* Documentation: [README.md](README.md)
* [gradle.properties](gradle.properties)
* **NOT** [CHANGES.md](CHANGES.md)!

5. Write release notes in [CHANGES.md](CHANGES.md):
* Follow the established style from the earlier release notes.
* Write each change on a single line (don't wrap with a caret return).
* Look through the commit messages since the previous release:
> `git log v<old-version>..`

Example: `git log v0.7.0..` lists the commits made since 0.7.0.

6. Create a new branch for this release:
> `git checkout -b version-<version>`

7. Commit and push the changes:
> `git commit -a -m 'Version <version>'`
> `git push -u origin version-<version>`

8. Open a GitHub pull request and review it.
Wait for the CI to finish.

### Publishing a normal release with the compatibility artifact

For the nearest future, **follow this subsection**.
When we no longer have the compatibility artifact, we'll remove the subsection.

9. Create a new branch from `version-<version>`:
> `git checkout -b version-<version>-compat version-<version>`

10. Replace `<version>` with `<version>-0.6.x-compat`
in [gradle.properties](gradle.properties).

11. Commit and push the changes:
> `git commit -a -m 'Version <version>, compatibility artifact`
> `git push -u origin version-<version>-compat`

12. Create another branch from `version-<version>`:
> `git checkout -b version-<version>-normal version-<version>`

13. Merge the `dkhalanskyjb/remove-deprecated-instant` branch:
> `git merge dkhalanskyjb/remove-deprecated-instant`

14. Push the changes:
> `git push -u origin version-<version>-normal`

15. Double-check the results.
The `normal` branch should be different from `compat` in having removed
a lot of code related to `kotlinx.datetime.Instant` and
`kotlinx.datetime.Clock` and having a `version-<version>` in
`gradle.properties` instead of `version-<version>-0.6.x-compat`.
> `git diff version-<version>-compat version-<version>-normal`

16. In TeamCity, start deployment of `version-<version>-compat` by running the
`Deployment/Start Deployment [RUN THIS ONE]` configuration:
<https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_StartDeployment>.
Use the `Run custom build` button.
- In the `Changes` tab, select the build branch `version-<version>-compat`.
- In the `Parameters` tab, set the parameters:
* `Version` to `<version>-0.6.x-compat`.
* Leave `VersionSuffix` blank.
* Leave `ZoneInfoVersion` blank.

17. Start deployment of `version-<version>-normal`.
- In the `Changes` tab, select the build branch `version-<version>-normal`.
- In the `Parameters` tab, set the parameters:
* `Version` to `<version>`.
* Leave `VersionSuffix` blank.
* Leave `ZoneInfoVersion` blank.

18. Wait for the *eight* deployment tasks to finish:
for both `version-<version>-normal` and `version-<version>-compat`,
`Start Deployment [RUN THIS ONE]`, `DeployCentral (Mac OS X)`,
`Deploy To Central`, and `Deploy ZoneInfo To Central` need to succeed.

19. Notify the release facilitator.
Publish the release cooperatively.
The artifacts to publish are:
- `kotlinx-datetime` version `<version>`.
- `kotlinx-datetime` version `<version>-0.6.x-compat`.
- `kotlinx-datetime-zoneinfo` version `<tzdb_tag>-spi.<version>`.
*NOT* `<tzdb_tag>-spi.<version>-0.6.x-compat`!

20. Merge `version-<version>` into `master`:
> `git checkout master`
> `git merge version-<version>`
> `git push`

21. In [GitHub](https://github.com/Kotlin/kotlinx-datetime):
* Create a release named `v<version>`, creating the `v<version>` tag.
* Cut & paste lines from [CHANGES.md](CHANGES.md) into the description.

22. Set the `latest-version` branch to `v<version>`.
> `git checkout latest-release`
> `git merge --ff-only master`
> `git push`

23. Announce the new release in [Slack](https://kotlinlang.slack.com).

24. Propose the website documentation update:
* In the `JetBrains/kotlin-web-site` repository:
- Update `dateTimeVersion` to `<version>` in
<https://github.com/JetBrains/kotlin-web-site/blob/master/docs/v.list>.
- Update `KOTLINX_DATETIME_RELEASE_LABEL` to `v<version>` in
<https://github.com/JetBrains/kotlin-web-site/blob/master/.teamcity/BuildParams.kt>.
- Create a pull request with the changes.
* In the `JetBrains/kotlin-compiler-server` repository:
- Update `kotlinx-datetime` to `<version>` in
<https://github.com/JetBrains/kotlin-compiler-server/blob/master/gradle/libs.versions.toml>
- Create a pull request with the changes.

25. Remove the `version-<version>-normal`, `version-<version>-compat`, and
`version-<version>` branches.

### Publishing a normal release

9. In TeamCity, start deployment of `version-<version>` by running the
`Deployment/Start Deployment [RUN THIS ONE]` configuration:
<https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_StartDeployment>.
Use the `Run custom build` button.
- In the `Changes` tab, select the build branch `version-<version>`.
- In the `Parameters` tab, set the parameters:
* `Version` to `<version>`.
* Leave `VersionSuffix` blank.
* Leave `ZoneInfoVersion` blank.

10. Wait for the *four* deployment tasks to finish:
`Start Deployment [RUN THIS ONE]`, `DeployCentral (Mac OS X)`,
`Deploy To Central`, and `Deploy ZoneInfo To Central` need to succeed.

11. Notify the release facilitator.
Publish the release cooperatively.
The artifacts to publish are:
- `kotlinx-datetime` version `<version>`.
- `kotlinx-datetime-zoneinfo` version `<tzdb_tag>-spi.<version>`.

12. Merge `version-<version>` into `master`:
> `git checkout master`
> `git merge version-<version>`
> `git push`

13. In [GitHub](https://github.com/Kotlin/kotlinx-datetime):
* Create a release named `v<version>`, creating the `v<version>` tag.
* Cut & paste lines from [CHANGES.md](CHANGES.md) into the description.

14. Set the `latest-version` branch to `v<version>`.
> `git checkout latest-release`
> `git merge --ff-only master`
> `git push`

15. Announce the new release in [Slack](https://kotlinlang.slack.com).

16. Propose the website documentation update:
* In the `JetBrains/kotlin-web-site` repository:
- Update `dateTimeVersion` to `<version>` in
<https://github.com/JetBrains/kotlin-web-site/blob/master/docs/v.list>.
- Update `KOTLINX_DATETIME_RELEASE_LABEL` to `v<version>` in
<https://github.com/JetBrains/kotlin-web-site/blob/master/.teamcity/BuildParams.kt>.
- Create a pull request with the changes.
* In the `JetBrains/kotlin-compiler-server` repository:
- Update `kotlinx-datetime` to `<version>` in
<https://github.com/JetBrains/kotlin-compiler-server/blob/master/gradle/libs.versions.toml>
- Create a pull request with the changes.

17. Remove the `version-<version>` branch.

## Publishing just the timezone database

> TODO: this section needs to be updated when either Kotlin/Wasm/WASI
reaches stability or we start publishing the timezone database for other
platforms.
Then, it will not be enough to just publish the database for the latest version,
we will need to publish the timezone database for the older `kotlinx-datetime`
versions as well.

1. Update the IANA timezone database as specified in
[UPDATE_TIMEZONE_DATABASE.md](UPDATE_TIMEZONE_DATABASE.md).
`tzdb-<tzdb_tag>` should now contain an up-to-date timezone database
that wasn't yet published.

2. In TeamCity, start deployment of `tzdb-<tzdb_tag>` by running the
`Deployment/Start Deployment [RUN THIS ONE]` configuration:
<https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_StartDeployment>.
Use the `Run custom build` button.
- In the `Changes` tab, select the build branch `tzdb-<tzdb_tag>`.
- In the `Parameters` tab, set the parameters:
* `Version` to the latest published `kotlinx-datetime` version.
Example: `0.7.1`.
* Leave `VersionSuffix` blank.
* Leave `ZoneInfoVersion` blank.

3. Wait for the *four* deployment tasks to finish:
`Start Deployment [RUN THIS ONE]`, `DeployCentral (Mac OS X)`,
`Deploy To Central`, and `Deploy ZoneInfo To Central` need to succeed.

4. Notify the release facilitator.
Publish the release cooperatively.
The artifact to publish is
`kotlinx-datetime-zoneinfo` version `<tzdb_tag>-spi.<latest_version>`.
95 changes: 95 additions & 0 deletions UPDATE_TIMEZONE_DATABASE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
# Updating the timezone database

If the build configuration <https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Check_Updates>
fails, the timezone databases bundled with `kotlinx-datetime` need updating.
This means either the IANA timezone database artifact provided for Wasm/WASI,
the Windows/IANA timezone name mapping, or both.

## Updating the IANA timezone database artifact

We publish a separate artifact for Wasm/WASI that includes
the IANA timezone database, as Wasm/WASI does not provide access to the
timezone database out of the box.
This means that whenever a new version of the timezone database gets published,
we need to release a new version of the artifact.

1. Ensure you have no changes in `timezones/full/tzdb/`:
> `git status timezones/full/tzdb/`

2. Check out `master`, make sure it's up to date:
> `git checkout master; git pull`

3. Visit <https://github.com/eggert/tz/tags> and note the latest available tag
(`<tzdb_tag>`).

4. Search & replace `<old_tzdb_tag>` with `<tzdb_tag>`.
- In `gradle.properties`, replace `tzdbVersion=<old_tzdb_tag>`
with `tzdbVersion=<tzdb_tag>`.
- In `README.md`,
replace `<old_tzdb_tag>` in the Gradle configuration snippet
with `<tzdb_tag>`.

5. Call the `:kotlinx-datetime-zoneinfo:tzdbDownloadAndCompile` Gradle task:
> `./gradlew tzdbDownloadAndCompile`

6. Create a new branch:
> `git checkout -b tzdb-<tzdb_tag>`

7. Commit and push the changes:
> `git commit timezones/full/tzdb -m 'Use IANA tzdb <tzdb_tag>'`
> `git push -u origin tzdb-<tzdb_tag>`

8. Create a GitHub pull request and review the changes.

9. Wait for the CI build to pass.

10. Follow the procedure for publishing a timezone database-only release
(see [RELEASE.md](RELEASE.md)).

11. Squash-and-merge the branch.

## Updating Windows/IANA timezone name mappings

Windows uses its own convention for timezone names.
We store internally the mapping between IANA timezone names
(which we use for all platforms as a standard) and the
Windows-specific names encountered in the Windows registry.

1. Stash the changes you have:
> `git stash`

2. Check out `master`, make sure it's up to date:
> `git checkout master; git pull`

3. Call the `:kotlinx-datetime:downloadWindowsZonesMapping` Gradle task:
> `./gradlew downloadWindowsZonesMapping`

4. If the task succeeds, the library already has the most up-to-date version
of the name mapping.
No actions are necessary.

5. If the task fails, it should say
`The new mappings were written to the filesystem.`.
Verify this by checking the difference:
> `git diff`

6. Create a new branch:
> `git checkout -b update-windows-tz-names`

7. Commit and push the changes:
> `git commit -a -m "Update the Windows/IANA timezone name mappings"`
> `git push -u origin update-windows-tz-names`

8. Create a GitHub pull request and review the changes.
Normally, the changes are small: only a few timezone names are added,
or some deprecated timezone names are removed.
Verify that this is the case.

9. Wait for the CI build to pass.

10. Squash-and-merge the changes and remove the branch on GitHub.
Then, also remove the branch locally:
> `git checkout master; git branch -D update-windows-tz-names`

11. Follow the procedure for publishing a new release
(see [RELEASE.md](RELEASE.md)) if new timezone names were added.