1# kotlinx.serialization release checklist 2 3To release new `<version>` of `kotlinx.serialization`: 4 51. Checkout `dev` branch and update:<br> 6 `git checkout dev && git pull` 7 83. Make sure the `master` branch is fully merged into `dev`:<br> 9 `git merge origin/master` 10 114. Search & replace `<old-version>` with `<version>` across the project files. Should replace in: 12 * [`README.md`](README.md) 13 * [`gradle.properties`](gradle.properties) 14 * [`integration-test/gradle.properties`](integration-test/gradle.properties) 15 16 Update Kotlin version, if necessary. 17 185. Write release notes in [`CHANGELOG.md`](CHANGELOG.md): 19 * Use old releases as example of style. 20 * Write each change on a single line (don't wrap with CR). 21 * Study commit message from previous release. 22 23 [git changelog](https://github.com/tj/git-extras/blob/master/Commands.md#git-changelog) from git-extras may help you with that. 24 256. If necessary, commit your changes to a new branch called `<version>-release` and send it for review, then merge it to `dev` branch.<br> 26If review is not required, commit directly to `dev`. 27 286. Tag version:<br> 29 `git tag v<version>` 30 318. Push your changes:<br> 32 `git push origin dev && git push origin --tags` 33 341. On [TeamCity integration server](https://teamcity.jetbrains.com/project.html?projectId=KotlinTools_KotlinxSerialization&tab=projectOverview): 35 * Wait until "Runtime library (Build – Aggregated)" configuration for committed `dev` branch passes tests. 36 * Run "Runtime library (Deploy - Train)" configuration: 37 * On 'Changes' tab, select `dev` branch and corresponding commit. 38 * On 'Parameters' tab, find 'Deploy version' and fill in with `<version>`. 39 404. In [Sonatype](https://oss.sonatype.org/#stagingRepositories) admin interface: 41 * Close the repository and wait for it to verify. 42 * Release it. 43 445. Set a new value for [`KOTLINX_SERIALIZATION_RELEASE_TAG`](https://github.com/JetBrains/kotlin-web-site/blob/master/.teamcity/BuildParams.kt), 45 creating a pull request in the website's repository. To find out why it is needed, [read this](#kotlinxserializationreleasetag). 46 476. Create a new release in [Github releases](https://github.com/Kotlin/kotlinx.serialization/releases). Use created git tag for title and changelog message for body. 48 491. Switch back to master branch and update it:<br> 50 ``` 51 git checkout master && git pull 52 git merge --ff-only dev 53 git push origin master 54 ``` 55 565. Announce new release in [Slack](https://kotlinlang.slack.com). 57 58# API reference documentation 59 60The [API reference documentation](https://kotlinlang.org/api/kotlinx.serialization/) is built and deployed automatically 61for every commit in `master`, typically within the same day. 62 63**Note**: KDoc / API reference changes targeting `master` should not contain information which is irrelevant to or is 64incorrect in relation to the latest release, because these changes will be deployed live automatically, and they might 65confuse readers. 66 67The build configuration responsible for assembling the documentation can be found 68[on TeamCity](https://buildserver.labs.intellij.net/buildConfiguration/Kotlin_KotlinSites_KotlinlangTeamcityDsl_KotlinxSerializationBuildApiReference). 69 70### KOTLINX_SERIALIZATION_RELEASE_TAG 71 72The generated API reference documentation has the library version specified in the header. By default, the value 73of the `version` project property is taken. However, this property usually contains the upcoming version with 74the `-SNAPSHOT` suffix, so it cannot be used if you want to publish the updated documentation of the latest release. 75 76For this reason, the [`KOTLINX_SERIALIZATION_RELEASE_TAG`](https://github.com/JetBrains/kotlin-web-site/blob/master/.teamcity/BuildParams.kt) 77property must be set during every release: its value will be used for all subsequent publications of the API docs to kotlinlang.org, 78and it will appear in the header. 79