Describe the release procedures

RELEASE.md

@@ -0,0 +1,229 @@
+# 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** [CHANGELOG.md](CHANGELOG.md)!
+
+5. Write release notes in [CHANGELOG.md](CHANGELOG.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 origin/latest-release..`
+
+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/Deploy [RUN THIS ONE]` configuration:
+   <https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Deploy_All>.
+   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`.
+     * `Artifacts to publish` to `core only`.
+
+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>`.
+     * `Artifacts to publish` to `all`.
+
+18. Wait for the two `Deployment/Upload deployment to central portal`
+   tasks to finish, one for `version-<version>-normal` and
+   one for `version-<version>-compat`:
+   <https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Deploy_Upload>.
+
+19. Click on the completed `Deployment/Upload deployment to central portal`
+   builds, check their `Artifacts` tabs.
+   They should have `deployment-<version>.zip` and `deployment-<version>-0.6.x-compat.zip`,
+   correspondingly.
+   Check the contents of these archives.
+   The non-compat archive should contain `kotlinx-datetime` with
+   version `<version>`, as well as the zoneinfo `<tzdb_tag>-spi.<version>`.
+   The compat archive should contain `kotlinx-datetime` with
+   version `<version>-0.6.x-compat`, but *NO* zoneinfo
+   `<tzdb_tag>-spi.<version>-0.6.x-compat`!
+   If all of this matches, approve the builds in
+   `Deployment/Publish deployment`:
+   <https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Deploy_Publish>.
+
+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,
+     based off of the `version-<version>-normal` branch.
+   * Cut & paste lines from [CHANGELOG.md](CHANGELOG.md) into the description.
+
+22. Set the `latest-release` branch to `v<version>`.
+   > `git checkout latest-release`
+   > `git merge --ff-only master`
+   > `git push`
+
+23. Create the `v<version>-0.6.x-compat` tag based off of the
+   `version-<version>-compat` branch:
+   > `git tag v<version>-0.6.x-compat version-<version>-compat`
+   > `git push --tags`
+
+24. Announce the new release in [Slack](https://kotlinlang.slack.com).
+
+25. 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.
+
+26. 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/Deploy [RUN THIS ONE]` configuration:
+   <https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Deploy_All>.
+   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>`.
+     * `Artifacts to publish` to `all`.
+
+10. Wait for the `Deployment/Upload deployment to central portal` task to finish:
+   <https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Deploy_Upload>.
+
+11. Click on the completed `Deployment/Upload deployment to central portal`
+   build, check its `Artifacts` tab, the `deployment-<version>.zip` archive.
+   It should contain `kotlinx-datetime` for all supported targets with
+   version `<version>`, as well as the zoneinfo `<tzdb_tag>-spi.<version>`.
+   If this matches, approve the build in `Deployment/Publish deployment`:
+   <https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Deploy_Publish>.
+
+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,
+     based off of the `master` branch.
+   * Cut & paste lines from [CHANGELOG.md](CHANGELOG.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/Deploy [RUN THIS ONE]` configuration:
+   <https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Deploy_All>.
+   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.8.0`.
+     * `Artifacts to publish` to `zoneinfo only`.
+
+3. Wait for the `Deployment/Upload deployment to central portal` task to finish:
+   <https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Deploy_Upload>.
+
+4. Click on the completed `Deployment/Upload deployment to central portal`
+   build, check its `Artifacts` tab, the `deployment-<version>.zip` archive
+   (where `<version>` is the latest published `kotlinx-datetime` version,
+   e.g. `0.8.0`).
+   It should contain the zoneinfo `<tzdb_tag>-spi.<version>` and nothing else.
+   If this matches, approve the build in `Deployment/Publish deployment`:
+   <https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Deploy_Publish>.

UPDATE_TIMEZONE_DATABASE.md

@@ -0,0 +1,113 @@
+# 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. Remove the existing timezone database:
+   > `rm -r timezones/*/tzdb`
+
+6. Call the `:kotlinx-datetime-zoneinfo:tzdbDownloadAndCompile` Gradle task:
+   > `./gradlew tzdbDownloadAndCompile`
+
+7. Create a new branch:
+   > `git checkout -b tzdb-<tzdb_tag>`
+
+8. Commit and push the changes:
+   > `git commit timezones/*/tzdb gradle.properties README.md -m 'Use IANA tzdb <tzdb_tag>';`
+   > `git push -u origin tzdb-<tzdb_tag>`
+
+9. Create a GitHub pull request and review the changes.
+
+10. Start the "Check for timezone database updates" CI build
+    with the `tzdb-<tzdb_tag>` branch.
+
+11. Wait for both the usual CI build and the
+    "Check for timezone database updates" one to pass.
+
+12. Follow the procedure for publishing a timezone database-only release
+   (see [RELEASE.md](RELEASE.md)).
+
+13. Squash-and-merge the branch.
+
+14. Start the "Check for timezone database updates" TeamCity build
+    and make sure it passes.
+
+## 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. Start the "Check for timezone database updates" CI build
+   with the `tzdb-<tzdb_tag>` branch.
+
+10. Wait for both the usual CI build and the
+    "Check for timezone database updates" one to pass.
+
+11. 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`
+
+12. Follow the procedure for publishing a new release
+   (see [RELEASE.md](RELEASE.md)) if new timezone names were added.
+
+13. Start the "Check for timezone database updates" TeamCity build
+    and make sure it passes.
+