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 steps:

• Creating release notes
• Tagging the code
• Creating the release using github
• Announcing the release
• Scheduling the next release
• Documenting the release

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

Tagging a Major-Minor release

Tag master branch with a vX.Y.Z version. This should be an annotated tag (it will have a commit message).

Example:

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

The go-ceph release notes have the following structure. Some of the boilerplate language in each section can be copied from the previous release notes and then updated:

• Introduction
• Highlights
• Stability caveat
• New features
• Now stable
• Deprecations and Removals
• Other

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

The "Highlights" are one or two paragraphs that highlight notable new feature(s) in the library. This includes a sentence or two describing the feature with a large impact to users of the library or one consumers were waiting for. If the contribution comes from someone who is not a project maintainer the paragraph should include a "shout out" to the contributor by name (usually taken from the contributor's signed-off-by line). We prefer to highlight changes from outside contributors whenever possible.

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

The "New Features" section is a bullet list of of the sub packages that make up go-ceph and then sub-lists for each new API call. If the feature is a C binding the line should be in the form Add [GoApiName] implementing [c_api_name]. Other calls and types can be listed like Add [GoApiName] function or Add [GoTypeName] method [GoFuncName]. If a method name is unambiguous feel free to skip documenting the type it recives, but if the name is not unique it may be best to include both the type and method like Add [GoTypeName] method [GoApiName] implementing [c_api_name].

Example:

# New Features

* In the rados package:
  * Add RambleOn implementing rados_ramble_on

* In the cephfs admin package:
  * Add SuperSecretSnapshot function

The "Now Stable" section consists of bulleted lists much like "New features". However, it lists lists APIs that were previously in the "preview" state and are now considered stable. The structure is the same as the "New Features" section but instead of Add [api] write The [api].

The "Deprecations and Removals" section can consist of API lists like the "New features" section when individual API calls are being deprecated. Lines take the form Deprecate [ApiName. It can also consist of free form paragraphs deprecating something like a ceph release or explaining a deprecation and it's expected replacements.

The "Other" section is a bulleted list containing short descriptions of changes to the codebase that don't fit the other categories. This include bugfixes, workflow/process changes, and minor non-API-visible improvements. Because most of these items are not visisble to codebases that make use of go-ceph, these lines can and should be short and avoid going into details. Eight commits to the code that make many changes can be summarized as "organizational changes to the code layout" for example. Parties interested in more can use git to explore the project history in detail.

Authoring process - A personal note

Generally, I use git log --reverse --oneline vX.Y.Z... to generate a summary of changes from the last release. I concatenate that to a copy of the previous release notes and then remove all the "old stuff". Then I go line by line through the "change log" removing the lines from git and adding a release note equivalent. One I've filled in the new features, deprecations, and now stable sections, I write the highlight. I then send it, as a draft, to the other maintainers and a few trusted colleagues for a brief review. I usually try to write the notes the day before the release.

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.