diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 00000000..59d3625d --- /dev/null +++ b/RELEASE.md @@ -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. + * + 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 `` with `` 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..` + + 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-` + +7. Commit and push the changes: + > `git commit -a -m 'Version '` + > `git push -u origin 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-`: + > `git checkout -b version--compat version-` + +10. Replace `` with `-0.6.x-compat` + in [gradle.properties](gradle.properties). + +11. Commit and push the changes: + > `git commit -a -m 'Version , compatibility artifact` + > `git push -u origin version--compat` + +12. Create another branch from `version-`: + > `git checkout -b version--normal version-` + +13. Merge the `dkhalanskyjb/remove-deprecated-instant` branch: + > `git merge dkhalanskyjb/remove-deprecated-instant` + +14. Push the changes: + > `git push -u origin 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-` in + `gradle.properties` instead of `version--0.6.x-compat`. + > `git diff version--compat version--normal` + +16. In TeamCity, start deployment of `version--compat` by running the + `Deployment/Start Deployment [RUN THIS ONE]` configuration: + . + Use the `Run custom build` button. + - In the `Changes` tab, select the build branch `version--compat`. + - In the `Parameters` tab, set the parameters: + * `Version` to `-0.6.x-compat`. + * Leave `VersionSuffix` blank. + * Leave `ZoneInfoVersion` blank. + +17. Start deployment of `version--normal`. + - In the `Changes` tab, select the build branch `version--normal`. + - In the `Parameters` tab, set the parameters: + * `Version` to ``. + * Leave `VersionSuffix` blank. + * Leave `ZoneInfoVersion` blank. + +18. Wait for the *eight* deployment tasks to finish: + for both `version--normal` and `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 ``. + - `kotlinx-datetime` version `-0.6.x-compat`. + - `kotlinx-datetime-zoneinfo` version `-spi.`. + *NOT* `-spi.-0.6.x-compat`! + +20. Merge `version-` into `master`: + > `git checkout master` + > `git merge version-` + > `git push` + +21. In [GitHub](https://github.com/Kotlin/kotlinx-datetime): + * Create a release named `v`, creating the `v` tag. + * Cut & paste lines from [CHANGES.md](CHANGES.md) into the description. + +22. Set the `latest-version` branch to `v`. + > `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 `` in + . + - Update `KOTLINX_DATETIME_RELEASE_LABEL` to `v` in + . + - Create a pull request with the changes. + * In the `JetBrains/kotlin-compiler-server` repository: + - Update `kotlinx-datetime` to `` in + + - Create a pull request with the changes. + +25. Remove the `version--normal`, `version--compat`, and + `version-` branches. + +### Publishing a normal release + +9. In TeamCity, start deployment of `version-` by running the + `Deployment/Start Deployment [RUN THIS ONE]` configuration: + . + Use the `Run custom build` button. + - In the `Changes` tab, select the build branch `version-`. + - In the `Parameters` tab, set the parameters: + * `Version` to ``. + * 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 ``. + - `kotlinx-datetime-zoneinfo` version `-spi.`. + +12. Merge `version-` into `master`: + > `git checkout master` + > `git merge version-` + > `git push` + +13. In [GitHub](https://github.com/Kotlin/kotlinx-datetime): + * Create a release named `v`, creating the `v` tag. + * Cut & paste lines from [CHANGES.md](CHANGES.md) into the description. + +14. Set the `latest-version` branch to `v`. + > `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 `` in + . + - Update `KOTLINX_DATETIME_RELEASE_LABEL` to `v` in + . + - Create a pull request with the changes. + * In the `JetBrains/kotlin-compiler-server` repository: + - Update `kotlinx-datetime` to `` in + + - Create a pull request with the changes. + +17. Remove the `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-` should now contain an up-to-date timezone database + that wasn't yet published. + +2. In TeamCity, start deployment of `tzdb-` by running the + `Deployment/Start Deployment [RUN THIS ONE]` configuration: + . + Use the `Run custom build` button. + - In the `Changes` tab, select the build branch `tzdb-`. + - 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 `-spi.`. diff --git a/UPDATE_TIMEZONE_DATABASE.md b/UPDATE_TIMEZONE_DATABASE.md new file mode 100644 index 00000000..d0f1d947 --- /dev/null +++ b/UPDATE_TIMEZONE_DATABASE.md @@ -0,0 +1,95 @@ +# Updating the timezone database + +If the build configuration +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 and note the latest available tag + (``). + +4. Search & replace `` with ``. + - In `gradle.properties`, replace `tzdbVersion=` + with `tzdbVersion=`. + - In `README.md`, + replace `` in the Gradle configuration snippet + with ``. + +5. Call the `:kotlinx-datetime-zoneinfo:tzdbDownloadAndCompile` Gradle task: + > `./gradlew tzdbDownloadAndCompile` + +6. Create a new branch: + > `git checkout -b tzdb-` + +7. Commit and push the changes: + > `git commit timezones/full/tzdb -m 'Use IANA tzdb '` + > `git push -u origin tzdb-` + +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.