kvcache-ai / kvcache-ai/Mooncake

[RFC]: Release Branch Workflow for Stable Releases

Open
#3,130 1 comment 3 reactions 0 assignees View on GitHub
RFC
Dominant language
C++
Stars
6.6k
Forks
1.2k
Avg merge
3d 5h
Merged PRs (30d)
312

Description

### Changes proposed

## Motivation

Our last release exposed several issues during the release process. We spent significant time resolving release-related problems, and after publishing the release, we discovered that the generated wheel package was broken, requiring an immediate `post1` release.

To reduce release risk and improve reproducibility, I propose the following release workflow.

## Proposal

For each release:

1. Create a dedicated `release` branch from `main`.
2. Treat the release branch as frozen. Only merge PRs that fix **critical release-blocking bugs**.
3. Trigger the release workflow to publish artifacts (especially wheels) to the **PyPI Test Repository**.
4. Verify that the generated packages can be installed and function correctly.
5. Once the artifacts are validated, publish the same release to the official PyPI repository.

## Benefits

* Provides a stable target for release validation.
* Prevents unrelated changes from entering a release while validation is in progress.
* Allows verification of the actual wheel artifacts before publishing to users.
* Reduces the likelihood of emergency post releases caused by packaging or release pipeline issues.

### Before submitting a new issue...

- [ ] Make sure you already searched for relevant issues and read the [documentation](https://kvcache-ai.github.io/Mooncake/)

Contributor guide

Open the contributing guide

Research direction

The proposal names no files, tests, or workflow entry points. Review the current release process and packaging workflow against the five proposed steps, then validate that the release branch can produce installable artifacts in the PyPI Test Repository before official publication.

Written by the indexing model from the issue text.

Assessment

Domain
ci-cd, release
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.