Skip to content

Commit f487af4

Browse files
dkhalanskyjbdkhalanskyjb
authored
Describe the release procedures (#562)
1 parent edc1183 commit f487af4

2 files changed

Lines changed: 342 additions & 0 deletions

File tree

‎RELEASE.md‎

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
# kotlinx-datetime release checklist
2+
3+
## Full release
4+
5+
To release `kotlinx-datetime`:
6+
7+
1. Make sure there are no updates to either Windows/IANA timezone name mapping
8+
or to the IANA timezone database that we publish.
9+
* <https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Check_Updates>
10+
checks this automatically every night.
11+
* Follow the procedure in
12+
[UPDATE_TIMEZONE_DATABASE.md](UPDATE_TIMEZONE_DATABASE.md)
13+
if there are updates or to check for updates manually.
14+
15+
2. Check out the `master` branch:
16+
> `git checkout master`
17+
18+
3. Retrieve the most recent version of it:
19+
> `git pull`
20+
21+
4. Search & replace `<old-version>` with `<version>` in
22+
* Documentation: [README.md](README.md)
23+
* [gradle.properties](gradle.properties)
24+
* **NOT** [CHANGELOG.md](CHANGELOG.md)!
25+
26+
5. Write release notes in [CHANGELOG.md](CHANGELOG.md):
27+
* Follow the established style from the earlier release notes.
28+
* Write each change on a single line (don't wrap with a caret return).
29+
* Look through the commit messages since the previous release:
30+
> `git log origin/latest-release..`
31+
32+
6. Create a new branch for this release:
33+
> `git checkout -b version-<version>`
34+
35+
7. Commit and push the changes:
36+
> `git commit -a -m 'Version <version>'`
37+
> `git push -u origin version-<version>`
38+
39+
8. Open a GitHub pull request and review it.
40+
Wait for the CI to finish.
41+
42+
### Publishing a normal release with the compatibility artifact
43+
44+
For the nearest future, **follow this subsection**.
45+
When we no longer have the compatibility artifact, we'll remove the subsection.
46+
47+
9. Create a new branch from `version-<version>`:
48+
> `git checkout -b version-<version>-compat version-<version>`
49+
50+
10. Replace `<version>` with `<version>-0.6.x-compat`
51+
in [gradle.properties](gradle.properties).
52+
53+
11. Commit and push the changes:
54+
> `git commit -a -m 'Version <version>, compatibility artifact'`
55+
> `git push -u origin version-<version>-compat`
56+
57+
12. Create another branch from `version-<version>`:
58+
> `git checkout -b version-<version>-normal version-<version>`
59+
60+
13. Merge the `dkhalanskyjb/remove-deprecated-instant` branch:
61+
> `git merge dkhalanskyjb/remove-deprecated-instant`
62+
63+
14. Push the changes:
64+
> `git push -u origin version-<version>-normal`
65+
66+
15. Double-check the results.
67+
The `normal` branch should be different from `compat` in having removed
68+
a lot of code related to `kotlinx.datetime.Instant` and
69+
`kotlinx.datetime.Clock` and having a `version-<version>` in
70+
`gradle.properties` instead of `version-<version>-0.6.x-compat`.
71+
> `git diff version-<version>-compat version-<version>-normal`
72+
73+
16. In TeamCity, start deployment of `version-<version>-compat` by running the
74+
`Deployment/Deploy [RUN THIS ONE]` configuration:
75+
<https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Deploy_All>.
76+
Use the `Run custom build` button.
77+
- In the `Changes` tab, select the build branch `version-<version>-compat`.
78+
- In the `Parameters` tab, set the parameters:
79+
* `Version` to `<version>-0.6.x-compat`.
80+
* `Artifacts to publish` to `core only`.
81+
82+
17. Start deployment of `version-<version>-normal`.
83+
- In the `Changes` tab, select the build branch `version-<version>-normal`.
84+
- In the `Parameters` tab, set the parameters:
85+
* `Version` to `<version>`.
86+
* `Artifacts to publish` to `all`.
87+
88+
18. Wait for the two `Deployment/Upload deployment to central portal`
89+
tasks to finish, one for `version-<version>-normal` and
90+
one for `version-<version>-compat`:
91+
<https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Deploy_Upload>.
92+
93+
19. Click on the completed `Deployment/Upload deployment to central portal`
94+
builds, check their `Artifacts` tabs.
95+
They should have `deployment-<version>.zip` and `deployment-<version>-0.6.x-compat.zip`,
96+
correspondingly.
97+
Check the contents of these archives.
98+
The non-compat archive should contain `kotlinx-datetime` with
99+
version `<version>`, as well as the zoneinfo `<tzdb_tag>-spi.<version>`.
100+
The compat archive should contain `kotlinx-datetime` with
101+
version `<version>-0.6.x-compat`, but *NO* zoneinfo
102+
`<tzdb_tag>-spi.<version>-0.6.x-compat`!
103+
If all of this matches, approve the builds in
104+
`Deployment/Publish deployment`:
105+
<https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Deploy_Publish>.
106+
107+
20. Merge `version-<version>` into `master`:
108+
> `git checkout master`
109+
> `git merge version-<version>`
110+
> `git push`
111+
112+
21. In [GitHub](https://github.com/Kotlin/kotlinx-datetime):
113+
* Create a release named `v<version>`, creating the `v<version>` tag,
114+
based off of the `version-<version>-normal` branch.
115+
* Cut & paste lines from [CHANGELOG.md](CHANGELOG.md) into the description.
116+
117+
22. Set the `latest-release` branch to `v<version>`.
118+
> `git checkout latest-release`
119+
> `git merge --ff-only master`
120+
> `git push`
121+
122+
23. Create the `v<version>-0.6.x-compat` tag based off of the
123+
`version-<version>-compat` branch:
124+
> `git tag v<version>-0.6.x-compat version-<version>-compat`
125+
> `git push --tags`
126+
127+
24. Announce the new release in [Slack](https://kotlinlang.slack.com).
128+
129+
25. Propose the website documentation update:
130+
* In the `JetBrains/kotlin-web-site` repository:
131+
- Update `dateTimeVersion` to `<version>` in
132+
<https://github.com/JetBrains/kotlin-web-site/blob/master/docs/v.list>.
133+
- Update `KOTLINX_DATETIME_RELEASE_LABEL` to `v<version>` in
134+
<https://github.com/JetBrains/kotlin-web-site/blob/master/.teamcity/BuildParams.kt>.
135+
- Create a pull request with the changes.
136+
* In the `JetBrains/kotlin-compiler-server` repository:
137+
- Update `kotlinx-datetime` to `<version>` in
138+
<https://github.com/JetBrains/kotlin-compiler-server/blob/master/gradle/libs.versions.toml>
139+
- Create a pull request with the changes.
140+
141+
26. Remove the `version-<version>-normal`, `version-<version>-compat`, and
142+
`version-<version>` branches.
143+
144+
### Publishing a normal release
145+
146+
9. In TeamCity, start deployment of `version-<version>` by running the
147+
`Deployment/Deploy [RUN THIS ONE]` configuration:
148+
<https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Deploy_All>.
149+
Use the `Run custom build` button.
150+
- In the `Changes` tab, select the build branch `version-<version>`.
151+
- In the `Parameters` tab, set the parameters:
152+
* `Version` to `<version>`.
153+
* `Artifacts to publish` to `all`.
154+
155+
10. Wait for the `Deployment/Upload deployment to central portal` task to finish:
156+
<https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Deploy_Upload>.
157+
158+
11. Click on the completed `Deployment/Upload deployment to central portal`
159+
build, check its `Artifacts` tab, the `deployment-<version>.zip` archive.
160+
It should contain `kotlinx-datetime` for all supported targets with
161+
version `<version>`, as well as the zoneinfo `<tzdb_tag>-spi.<version>`.
162+
If this matches, approve the build in `Deployment/Publish deployment`:
163+
<https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Deploy_Publish>.
164+
165+
12. Merge `version-<version>` into `master`:
166+
> `git checkout master`
167+
> `git merge version-<version>`
168+
> `git push`
169+
170+
13. In [GitHub](https://github.com/Kotlin/kotlinx-datetime):
171+
* Create a release named `v<version>`, creating the `v<version>` tag,
172+
based off of the `master` branch.
173+
* Cut & paste lines from [CHANGELOG.md](CHANGELOG.md) into the description.
174+
175+
14. Set the `latest-version` branch to `v<version>`.
176+
> `git checkout latest-release`
177+
> `git merge --ff-only master`
178+
> `git push`
179+
180+
15. Announce the new release in [Slack](https://kotlinlang.slack.com).
181+
182+
16. Propose the website documentation update:
183+
* In the `JetBrains/kotlin-web-site` repository:
184+
- Update `dateTimeVersion` to `<version>` in
185+
<https://github.com/JetBrains/kotlin-web-site/blob/master/docs/v.list>.
186+
- Update `KOTLINX_DATETIME_RELEASE_LABEL` to `v<version>` in
187+
<https://github.com/JetBrains/kotlin-web-site/blob/master/.teamcity/BuildParams.kt>.
188+
- Create a pull request with the changes.
189+
* In the `JetBrains/kotlin-compiler-server` repository:
190+
- Update `kotlinx-datetime` to `<version>` in
191+
<https://github.com/JetBrains/kotlin-compiler-server/blob/master/gradle/libs.versions.toml>
192+
- Create a pull request with the changes.
193+
194+
17. Remove the `version-<version>` branch.
195+
196+
## Publishing just the timezone database
197+
198+
> TODO: this section needs to be updated when either Kotlin/Wasm/WASI
199+
reaches stability or we start publishing the timezone database for other
200+
platforms.
201+
Then, it will not be enough to just publish the database for the latest version,
202+
we will need to publish the timezone database for the older `kotlinx-datetime`
203+
versions as well.
204+
205+
1. Update the IANA timezone database as specified in
206+
[UPDATE_TIMEZONE_DATABASE.md](UPDATE_TIMEZONE_DATABASE.md).
207+
`tzdb-<tzdb_tag>` should now contain an up-to-date timezone database
208+
that wasn't yet published.
209+
210+
2. In TeamCity, start deployment of `tzdb-<tzdb_tag>` by running the
211+
`Deployment/Deploy [RUN THIS ONE]` configuration:
212+
<https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Deploy_All>.
213+
Use the `Run custom build` button.
214+
- In the `Changes` tab, select the build branch `tzdb-<tzdb_tag>`.
215+
- In the `Parameters` tab, set the parameters:
216+
* `Version` to the latest published `kotlinx-datetime` version.
217+
Example: `0.8.0`.
218+
* `Artifacts to publish` to `zoneinfo only`.
219+
220+
3. Wait for the `Deployment/Upload deployment to central portal` task to finish:
221+
<https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Deploy_Upload>.
222+
223+
4. Click on the completed `Deployment/Upload deployment to central portal`
224+
build, check its `Artifacts` tab, the `deployment-<version>.zip` archive
225+
(where `<version>` is the latest published `kotlinx-datetime` version,
226+
e.g. `0.8.0`).
227+
It should contain the zoneinfo `<tzdb_tag>-spi.<version>` and nothing else.
228+
If this matches, approve the build in `Deployment/Publish deployment`:
229+
<https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Deploy_Publish>.

‎UPDATE_TIMEZONE_DATABASE.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Updating the timezone database
2+
3+
If the build configuration <https://teamcity.jetbrains.com/buildConfiguration/KotlinTools_KotlinxDatetime_Check_Updates>
4+
fails, the timezone databases bundled with `kotlinx-datetime` need updating.
5+
This means either the IANA timezone database artifact provided for Wasm/WASI,
6+
the Windows/IANA timezone name mapping, or both.
7+
8+
## Updating the IANA timezone database artifact
9+
10+
We publish a separate artifact for Wasm/WASI that includes
11+
the IANA timezone database, as Wasm/WASI does not provide access to the
12+
timezone database out of the box.
13+
This means that whenever a new version of the timezone database gets published,
14+
we need to release a new version of the artifact.
15+
16+
1. Ensure you have no changes in `timezones/full/tzdb/`:
17+
> `git status timezones/full/tzdb/`
18+
19+
2. Check out `master`, make sure it's up to date:
20+
> `git checkout master; git pull`
21+
22+
3. Visit <https://github.com/eggert/tz/tags> and note the latest available tag
23+
(`<tzdb_tag>`).
24+
25+
4. Search & replace `<old_tzdb_tag>` with `<tzdb_tag>`.
26+
- In `gradle.properties`, replace `tzdbVersion=<old_tzdb_tag>`
27+
with `tzdbVersion=<tzdb_tag>`.
28+
- In `README.md`,
29+
replace `<old_tzdb_tag>` in the Gradle configuration snippet
30+
with `<tzdb_tag>`.
31+
32+
5. Remove the existing timezone database:
33+
> `rm -r timezones/*/tzdb`
34+
35+
6. Call the `:kotlinx-datetime-zoneinfo:tzdbDownloadAndCompile` Gradle task:
36+
> `./gradlew tzdbDownloadAndCompile`
37+
38+
7. Create a new branch:
39+
> `git checkout -b tzdb-<tzdb_tag>`
40+
41+
8. Commit and push the changes:
42+
> `git commit timezones/*/tzdb gradle.properties README.md -m 'Use IANA tzdb <tzdb_tag>';`
43+
> `git push -u origin tzdb-<tzdb_tag>`
44+
45+
9. Create a GitHub pull request and review the changes.
46+
47+
10. Start the "Check for timezone database updates" CI build
48+
with the `tzdb-<tzdb_tag>` branch.
49+
50+
11. Wait for both the usual CI build and the
51+
"Check for timezone database updates" one to pass.
52+
53+
12. Follow the procedure for publishing a timezone database-only release
54+
(see [RELEASE.md](RELEASE.md)).
55+
56+
13. Squash-and-merge the branch.
57+
58+
14. Start the "Check for timezone database updates" TeamCity build
59+
and make sure it passes.
60+
61+
## Updating Windows/IANA timezone name mappings
62+
63+
Windows uses its own convention for timezone names.
64+
We store internally the mapping between IANA timezone names
65+
(which we use for all platforms as a standard) and the
66+
Windows-specific names encountered in the Windows registry.
67+
68+
1. Stash the changes you have:
69+
> `git stash`
70+
71+
2. Check out `master`, make sure it's up to date:
72+
> `git checkout master; git pull`
73+
74+
3. Call the `:kotlinx-datetime:downloadWindowsZonesMapping` Gradle task:
75+
> `./gradlew downloadWindowsZonesMapping`
76+
77+
4. If the task succeeds, the library already has the most up-to-date version
78+
of the name mapping.
79+
No actions are necessary.
80+
81+
5. If the task fails, it should say
82+
`The new mappings were written to the filesystem.`.
83+
Verify this by checking the difference:
84+
> `git diff`
85+
86+
6. Create a new branch:
87+
> `git checkout -b update-windows-tz-names`
88+
89+
7. Commit and push the changes:
90+
> `git commit -a -m "Update the Windows/IANA timezone name mappings"`
91+
> `git push -u origin update-windows-tz-names`
92+
93+
8. Create a GitHub pull request and review the changes.
94+
Normally, the changes are small: only a few timezone names are added,
95+
or some deprecated timezone names are removed.
96+
Verify that this is the case.
97+
98+
9. Start the "Check for timezone database updates" CI build
99+
with the `tzdb-<tzdb_tag>` branch.
100+
101+
10. Wait for both the usual CI build and the
102+
"Check for timezone database updates" one to pass.
103+
104+
11. Squash-and-merge the changes and remove the branch on GitHub.
105+
Then, also remove the branch locally:
106+
> `git checkout master; git branch -D update-windows-tz-names`
107+
108+
12. Follow the procedure for publishing a new release
109+
(see [RELEASE.md](RELEASE.md)) if new timezone names were added.
110+
111+
13. Start the "Check for timezone database updates" TeamCity build
112+
and make sure it passes.
113+

0 commit comments

Comments
 (0)