go-ceph/docs/release-process.md

Go-Ceph Release Process

Regular releases are planned starting mid-February 2020. Until the API is stable we will be issuing v0.y versions.

Today, the release process includes the following stages:

Pre-release

• Complete any API stability updates
  • if issue "APIs pending stability updates" exists:
    • remove ceph_preview constraints from related files
    • run make api-promote
  • run make api-fix-versions for new APIs
• Check milestone for any incomplete issues
• Update the releases table in the README

Release Tasks

• Tag the code
• Create release notes
• Finalize the release on GitHub

Post-release

• Announce the release
• Create/verify a milestone for next release
• Prepare API stability update issue for next release

The sections below go into more detail about these steps in no particular order.

Tagging a Major-Minor release

First, make sure your local git tree has the latest changes. Tag master branch with a vX.Y.Z version. This should be an annotated tag (it will have a commit message).

Example:

git checkout master
git pull --ff-only
git tag -a v0.2.0 -m 'Release v0.2.0'

Push the tag to the go-ceph repo (not your own fork). Example:

git push --follow-tags

Create a release using github

• https://github.com/ceph/go-ceph/releases/new
• Select the tag you just pushed
• Add the release notes to the body of the release
• Save the new release

After creating the release the milestone for the release should be closed (edit milestone -> close).

Notes

As a Go library package that makes use of cgo we will not be producing any build artifacts at this time. Only source code will be provided. Users of the library will typically use the go toolchain (go modules, etc), git or tarballs. Tarballs are automatically provided by github interface when a release is created. No extra steps are currently required.

Scheduling the next release

Future releases are scheduled using the milestones feature on github. The milestone may have features/issues/PRs associated with it, but it does not have to. The milestone must have a date associated with it.

Currently, go-ceph is released every two months. The project has a tradition of releasing on a Tuesday, and a Tuesday near the middle of the month. Often, this is the second Tuesday of the month. However, if the first or second day of the month is a Tuesday it may be better to choose the 3rd Tuesday of the month.

The title of the milestone should be "Release vX.Y.Z" where X, Y, and Z are the major, minor, and patch versions. The description is short typically just, "Regular planned release vX.Y of the go-ceph library." Since go-ceph is using time based released additional details are largely unnecessary.

So, for example if the release is occurring on Tuesday, Feb. 15, 2022 then the next release day would be April. The second Tuesday of April is the 12th. So the due date would be set to 2022-04-12.

Because of the time based process it is fine to create the new milestones before the current release is done.

Creating release notes

As of release v0.15.0 the method of writing release notes is largely based on using the automatically generated list of PRs generated at GitHub's Release UI and then sorting some of the items into categories. Some of the boilerplate language in each section can be copied from the previous release notes and then updated.

Remember, one of the easiest things to do is to look at previous releases and largely mimic what they do.

Introduction

The "Introduction" is a paragraph noting that this is a new version of go-ceph. It can be copied and the version updated.

Highlights

Thank new contributors to the project. This can be derived from the GitHub notes. Additional paragraphs can be added to highlight a particularly important feature or change.

Stability Caveat

The "Stability caveat" is a reminder about go-ceph's stability (non)guarantees. It can be copied from previous releases.

New Features

Sort new features by package (cephfs, rados, rbd/admin, etc). Each PR/change-list is a bullet point under the package. For every PR that adds an API add a sub-bullet describing new methods and what methods in Ceph it wraps (if it wraps something).

API Stability Updates

Sort changes by package. For each changed API make a bullet point and describe the state of the API ("x is now stable", etc).

Deprecations and Removals

Sort API function changes by package. Note what APIs that are deprecated and/or what is removed. Add a short paragraph describing any changes to what versions of Ceph is being deprecated or removed.

Internal

The internal changes list is a flat bulleted list of changes (PRs) that do not add or remove Go-package-visible features. Things like changes to the build scripts or unit tests, for example.

NOTE: For context on how previous versions of the release notes were authored please review older versions of this file from version control history.

Announcing the release

The release is publicly announced to ceph-devel and ceph users mailing lists. The body of the email follows the template below. Change the URL to point to the new release. Optionally mention some of the packages that have changes:

I'm happy to announce another release of the go-ceph API library. This is a
regular release following our every-two-months release cadence.

https://github.com/ceph/go-ceph/releases/tag/v0.13.0

Changes include additions to the rbd and rados packages. More details are
available at the link above.

The library includes bindings that aim to play a similar role to the "pybind"
python bindings in the ceph tree but for the Go language. The library also
includes additional APIs that can be used to administer cephfs, rbd, and rgw
subsystems.
There are already a few consumers of this library in the wild, including the
ceph-csi project.

This announcement is also sent to an internal team list inside Red Hat.

Documenting the Release

The README.md file contains a table of go-ceph releases and what versions of ceph each release supports. After the release has been created this table should be updated to reflect the new release and what versions of ceph it supports.