Label-Based Version Control Strategy

[GreatEugenius]

Overview

We want to introduce a version control strategy using labels, primarily inspired by the label strategy in Apache Pulsar.

Label Definition

Priority

For an issue or PR, there are three levels of priority: blocker, major, and minor, listed in descending order. Below are the meanings of the three labels:

Label	Description
priority/blocker	Indicate the PR or issue that should block the release until it gets resolved.
priority/major	Default priority of the PR or issue.
priority/minor	Indicate the PR or issue related to non-urgent bugs, features, and improvements.

Version and Branch Control

Label	Description
fixVersion/<version>	The feature or bug should be implemented/fix in the <version> version.
affectedVersion/<version>	The bug affects the <version> version. The features are not needed.

Document Management

When submitting a PR, you must choose one of the documentation checkboxes, so the automation can label the PR correctly.

Label	Description
doc-needed	Your PR changes impact docs.
doc-not-needed	Your PR changes do not impact docs
doc-label-missing	The Bot applies this label when there is no documentation label information in the PR, either because you did not provide a documentation label or because you provided multiple documentation labels.

Usage Scenarios

Feature

If the user needs a new feature, they can check for any related Issues or PRs. If there are any, they can choose to upgrade to the corresponding version using the fixVersion/<version> tag. If not, they should proceed to the steps below:

1. Issue Creation

   1. A user or developer identifies a new feature request and opens an issue in the project repository.
   2. Automatically added labels:  priority/major , feature.

2. Requirement Review

   1. The development team reviews the feature request and assesses its feasibility. Based on the timeline, select the appropriate fixVersion/<version> label.
   2. The development team may adjust the priority label to priority/blocker, priority/minor, depending on importance and impact.

3. Development Implementation

   1. After completing the implementation, a developer open a pull request (PR) to the corresponding branch.
   2. The PR document must indicate whether the changes affect user documentation.
   3. Automatically added labels include priority/major, doc-* and fixVersion/<branch_next_version>, where <branch_next_version> represents the next release version of the current branch.
   4. . Add the label fixVersion/<version> if the change needs to be cherry-picked into the stable branch, where <version> is the next version that the branch will release.

4. Code Review and PR Closure

   1. A Committer reviews the PR and approves it. If the PR has a doc-needed label, it must include documentation changes or a sub-track issue created with a priority/blocker label.
   2. Upon seeing the fixVersion/<version> label, the Committer try to cherry-pick of the commit into the corresponding branch:
      1. If the attempt fails, the committer should remove the fixVersion/<version> label from the PR and ask the contributor to open another PR against the corresponding branch.
   3. After all commits are merged into the corresponding branches, the PR can be closed as merged.
   4. If developers find that the feature is abandoned, a Committer or Release Manager can simply close the PR.

5. Issue Closure

   1. Check all the fixVersion/<version> labels in the Issue. If the corresponding versions are all fixed, a Committer or Release Manager will close the issue  as completed.
   2. If the feature is abandoned, a Committer or Release Manager will close the issue as not planned and remove all fixVersion/<version> labels.

Bug

If the user discovery a bug, they can check for any related Issues or PRs. If there are any, they can choose to upgrade to the corresponding version using the fixVersion/<version> label. If not, they should proceed to the steps below:

1. Bug Discovery and Issue Creation

   1. A user encounters a bug while running Flink agents jobs.
   2. He open an issue in the project repository.
   3. The issue includes documentation of the problem and specifies that the affected version is <report_version>.
   4. Since the issue has just been reported, there is no need to manually add labels at this stage; only the automatically added labels: priority/major and bug are included.
   5. A Collaborator may later change the priority label (e.g., priority/blocker or priority/minor) based on severity and impact.

2. Bug Analysis

   1. A developer identifies the root cause of the bug and determines that it affects all the relevant versions. Then adds the affectedVersion/<version> labels to the issue based on the release timeline.
   2. Add the fixVersion/<version> labels to the issue based on the release timeline.

3. Bug Fix

   1. The developer opens a pull request (PR) to fix the bug on the main branch.
   2. Automatically added labels: priority/major, doc-* and fixVersion/<branch_next_version>.
   3. Add the label fixVersion/<version> if  the fix should cherry-picked into another branch, where <version> is the next version that the branch will release.

4. Code Review and PR Closure

   1. A Committer reviews the PR and approves it.
   2. Upon seeing the fixVersion/<version> label, the Committer try to cherry-pick of the commit into the corresponding branch:
      1. If the attempt fails, the committer should remove the fixVersion/<version> label from the PR and ask the contributor to open another PR against the corresponding branch.
   3. After all commits are merged into the corresponding branches, the PR can be closed as merged.
   4. If developers find that the bug fix is invalid, a Committer or Release Manager can simply close the PR.

5. Issue Closure

   1. Check all the fixVersion/<version> labels in the Issue. If the corresponding versions are all fixed, a Committer or Release Manager will close the issue as completed.
   2. If the bug is invalid, a Committer or Release Manager will close the issue as not planned and remove all fixVersion/<version> and affectedVersion/<version> labels.
   3. If the bug is valid but won't be fixed (for versions that are no longer maintained), a Committer or Release Manager will close the issue as not planned and will only remove all affectedVersion/<version> labels.

Release

1. Release Prepare

   1. When preparing to release a new version, the Release Manager should check for any pull requests or issues labeled fixVersion/<version> that are not closed. 
   2. For PRs or issues labeled as priority/blocker, the Release Manager should wait for their resolution or deprioritize them.
   3. For PRs or issues labeled as priority/major or priority/minor, the Release Manager may elevate the priority to priority/blocker if they need to be included in this release.

2. Release a New Version: 

   1. Release Manager creates a new label fixVersion/<version>, where <version> is the next upcoming version after the release.
   2. Release Manager creates a new label affectedVersion/<version>, where <version> represents the version being released.
   3. For example, if releasing version 0.1.1, add labels affectedVersion/0.1.1 and fixVersion/0.1.2.

3. If Create a New Release Branch

   1. Release Manager create a new label named fixVersion/<version>, where <version> represents the title of the new main branch.

4. After releasing

   1. Release Manager should check recent commits to ensure the fixVersion/<version> label is accurate.
   2. The Release Manager should change the label for all open PRs or issues from fixVersion/<release_version> to fixVersion/<upcoming_version>.
   3. For example, when releasing version 0.1.0, the Release Manager should update all open PRs or issues from fixVersion/0.1.0 to either fixVersion/0.2.0 or fixVersion/0.1.1, depending on whether it is a feature or a bug.