Skip to content
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
165 changes: 138 additions & 27 deletions version-release.md
Original file line number Diff line number Diff line change
@@ -1,30 +1,141 @@
# Volcano Version Release

This document describes how the Volcano community plans and publishes releases
for Volcano and its subprojects.

## Versioning

Volcano projects use versions in the `X.Y.Z` format.

* `X` is the major version. It is increased when a release contains
incompatible API, behavior, or dependency changes.
* `Y` is the minor version. It is increased for regular feature releases that
keep backward compatibility as much as possible.
* `Z` is the patch version. It is increased for bug fixes, security fixes,
dependency updates, or packaging and documentation fixes that do not introduce
new features.

For example, `1.13.2` means major version `1`, minor version `13`, and patch
version `2`.

Pre-release versions may be published when the maintainers think broader testing
is needed before an official release.

## Release Cadence

Volcano projects may follow different release cadences according to project
status, user requirements, and community discussion.
Comment on lines +26 to +27

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Using 'depending on project status' is more idiomatic than 'according to project status'.

Suggested change
Volcano projects may follow different release cadences according to project
status, user requirements, and community discussion.
Volcano projects may follow different release cadences depending on project
status, user requirements, and community discussion.


The Volcano main repository usually publishes a minor release every four months.
Release planning normally starts about one month before the target release date.
The release manager collects requirements, confirms the release scope, tracks
release blockers, and publishes the release plan to the community.

Some subprojects with a clear release plan may use their own cadence. For
example, Kthena usually publishes a minor release about every three months. The
cadence of such projects should be discussed in the community and reflected in
the project roadmap or release plan.

Other Volcano projects may use a flexible release cadence. They can publish a
release when there are enough feature updates, important bug fixes,
compatibility updates, or user requirements. Maintainers should still announce
the planned release scope and timeline in the community whenever possible.

## Version Plan
Version plan is usually put into practice **half month** before the latest version released.
#### Requirements Collection
According to the feedback of community, we will collect requirements which are from **classical scenes** or **common
demands** in the last three months. All collected requirements will be listed in the requirements list, reviewed initially,
and prioritized.
#### Community Review
Requirement list will be submitted to the community weekly meeting for discussion. Community members will evaluate the
scenarios, rationality, feature design points, development workload and other dimensions of the requirements. After the
discussion, part of requirements will be settled as version features and published in the roadmap.

### Version Release
Generally, we will release an official version such as 1.X every **three months**. Bug fix versions such as 1.X.X are
released any time we consider it necessary after some important bug fixed.
#### Code Freeze
In order to ensure the quality of master branch, repository will be frozen **two weeks** before official version released,
during which only bug fix PRs are admitted to be merged. **Alpha** and **Beta** version also will be released in the period.
#### Branch Checkout
During the code frozen, a new branch whose name like `release-X.X.X` will be checkout to merge bug fix and published release.
#### Release Publishment
We will publish every release and related docker images. Users can find release in the release list and docker images in
the DockerHub.
#### Beta Test
After every release published, some users and community members will be invited to join the Beta test. Any contributor is
welcome to take part in the test. We will collect bug feedback and fix them immediately. Usually, this work will be going
**one week** before official release published.
#### Official Release Publishment
After all the work above finished, official release will be published with note about feature introduction.

Version planning is an ongoing activity during the release cycle. Some work
items are planned before the cycle starts, while others may be added later based
on user feedback, community discussion, bug reports, or dependency changes.

The community may use GitHub Projects, issues, milestones, or roadmap documents
to track work items that are being considered for the next release. These lists
help contributors understand the current focus of the release, but they are not
a strict commitment that every listed item must be completed in that release.

### Requirements Collection

According to the feedback of community, we will collect requirements from
classical scenes or common demands. Requirements can also come from open issues,
Comment on lines +57 to +58

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The phrase 'feedback of community' is grammatically awkward, and 'classical scenes' is a literal translation of a Chinese idiom (经典场景) that is better translated as 'typical scenarios' or 'common use cases' in English.

Suggested change
According to the feedback of community, we will collect requirements from
classical scenes or common demands. Requirements can also come from open issues,
According to community feedback, we will collect requirements from
typical scenarios or common demands.

pull requests, user cases, compatibility work, and maintainer proposals. The
release manager and maintainers may group related items and keep them in the
release tracking list for follow-up.

### Community Review

The requirement list can be submitted to the community meeting or discussed in
public issues and pull requests. Community members may evaluate the scenarios,
rationality, feature design points, development workload, compatibility impact,
test plan, documentation updates, and other dimensions of the requirements.

After the discussion, items that are ready and have enough owner support may be
included in the roadmap or release plan. Items that are still under design,
lack owners, or have unresolved compatibility concerns may be moved to a later
release.

## Version Release

### Release Branch

Before publishing a release, a new branch whose name is like `release-X.Y` or
`release-X.Y.Z` will be checked out to prepare the release. The exact branch
name can follow the convention of each repository.

Release related bug fixes, regression fixes, security fixes, documentation

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The compound modifier 'Release related' should be hyphenated as 'Release-related' for proper grammar.

Suggested change
Release related bug fixes, regression fixes, security fixes, documentation
Release-related bug fixes, regression fixes, security fixes, documentation

fixes, and release engineering changes can be merged into the release branch.
Normal development may continue on master during the release period.

### Release Stabilization

Before the official release is published, maintainers should focus on release
blocking issues, compatibility problems, installation problems, and important
regressions found during community testing.

Users and community members are welcome to test the release branch or
pre-release artifacts if they are available. Feedback should be tracked in
public issues or pull requests whenever possible.

### Release Publication

We will publish every official release and related artifacts, such as source
archives, release notes, docker images, charts, or packages according to the

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

'Docker' is a proper noun and should be capitalized.

Suggested change
archives, release notes, docker images, charts, or packages according to the
archives, release notes, Docker images, charts, or packages according to the

project. Users can find release artifacts in the release list and corresponding
image registry or package registry.

## Patch Release

Bug fix versions such as `X.Y.Z` are released any time we consider it necessary
after important bugs are fixed. Patch releases do not have a fixed cadence.

A patch release may be created for important bug fixes, security fixes,
Kubernetes or dependency compatibility fixes, regressions introduced by a recent
release, or packaging and installation fixes that affect users.

Patch releases should not include new features or intentional compatibility
breaks. Feature work should go to master and be included in a future minor or
major release.

## Supported Versions

Patch fixes are maintained for the current master branch and the latest three
release branches. When a new minor version is released, the supported release
branches move forward together.

For example, if the latest release branch is `release-1.13`, patch fixes may be
maintained for master, `release-1.13`, `release-1.12`, and `release-1.11`. After
`release-1.14` is published, the maintained branches become master,
`release-1.14`, `release-1.13`, and `release-1.12`. Earlier release branches
will no longer receive patch releases.

Only important bug fixes, security fixes, and low-risk compatibility fixes are
backported to supported release branches. Feature changes are not backported.

Backports should be evaluated case by case. A fix is suitable for backporting
when it is important for users, has acceptable risk, can be tested on the target
branch, and does not require large feature changes.

## Exceptions

The release manager and maintainers may adjust the release date, release scope,
or supported patch branches when required by quality, security, compatibility,
or maintainer availability. Any significant change should be announced to the
community in advance whenever possible.