kotlinx.serialization release checklist

To release new <version> of kotlinx.serialization:

  1. Checkout dev branch and update:
    git checkout dev && git pull

  2. Make sure the master branch is fully merged into dev:
    git merge origin/master

  3. Search & replace <old-version> with <version> across the project files. Should replace in:

    Update Kotlin version, if necessary.

  4. Write release notes in CHANGELOG.md:

    • Use old releases as example of style.
    • Write each change on a single line (don't wrap with CR).
    • Study commit message from previous release.

    git changelog from git-extras may help you with that.

  5. If necessary, commit your changes to a new branch called <version>-release and send it for review, then merge it to dev branch.
    If review is not required, commit directly to dev.

  6. Tag version:
    git tag v<version>

  7. Push your changes:
    git push origin dev && git push origin --tags

  8. On TeamCity integration server:

    • Wait until "Runtime library (Build – Aggregated)" configuration for committed dev branch passes tests.
    • Run "Runtime library (Deploy - Train)" configuration:
      • On 'Changes' tab, select dev branch and corresponding commit.
      • On 'Parameters' tab, find 'Deploy version' and fill in with <version>.

  9. In Sonatype admin interface:

    • Close the repository and wait for it to verify.
    • Release it.

  10. Set a new value for KOTLINX_SERIALIZATION_RELEASE_TAG, creating a pull request in the website's repository. To find out why it is needed, read this.

  11. Create a new release in Github releases. Use created git tag for title and changelog message for body.

  12. Switch back to master branch and update it:

    git checkout master && git pull
git merge --ff-only dev
git push origin master

  13. Announce new release in Slack.

API reference documentation

The API reference documentation is built and deployed automatically for every commit in master, typically within the same day.

Note: KDoc / API reference changes targeting master should not contain information which is irrelevant to or is incorrect in relation to the latest release, because these changes will be deployed live automatically, and they might confuse readers.

The build configuration responsible for assembling the documentation can be found on TeamCity.

KOTLINX_SERIALIZATION_RELEASE_TAG

The generated API reference documentation has the library version specified in the header. By default, the value of the version project property is taken. However, this property usually contains the upcoming version with the -SNAPSHOT suffix, so it cannot be used if you want to publish the updated documentation of the latest release.

For this reason, the KOTLINX_SERIALIZATION_RELEASE_TAG property must be set during every release: its value will be used for all subsequent publications of the API docs to kotlinlang.org, and it will appear in the header.