[Proposal] Adopting a PostgreSQL-Style Branching Strategy with Semantic Versioning (SemVer) for the Cloudberry Project

[edespino]

Proposers

@edespino

Proposal Status

Under Discussion

Abstract

This proposal recommends adopting a PostgreSQL-style branching strategy for the Cloudberry project, combined with strict adherence to Semantic Versioning (SemVer). The strategy will ensure that the main branch remains stable and production-ready, while development, releases, and long-term maintenance are managed efficiently and transparently. The initial release branch will be named REL_1_STABLE. We are targeting implementation during the week of August 26, with the initial Cloudberry 1.6.0 release planned for September 3rd.

Motivation

• Stability: Ensuring that the main branch is always stable and ready for production deployment is critical for maintaining the integrity of the Cloudberry project. This approach minimizes the risk of introducing bugs or unstable features into the codebase.
• Clarity: Semantic Versioning (SemVer) provides a clear, standardized method for versioning releases, making it easy for users and developers to understand the significance of each update and its impact on compatibility.
• Effective Maintenance: A structured branching strategy with designated release branches allows for consistent support and maintenance of older versions, ensuring that critical updates and security patches can be applied without disrupting ongoing development.

Implementation

Branching Strategy:

1. Main Branch (main):

• Purpose: The main branch will serve as the stable, production-ready branch. It will only contain code that has been thoroughly tested and approved for release.
• Usage: Changes to main will be made by merging stable, well-tested code from completed development feature branches, release branches, or hotfix branches.

2. Initial Release Branch (REL_1_STABLE):

• Purpose: This branch will be used to manage the final stages of preparing and maintaining the 1.x series of Cloudberry releases.
• Flow: Future point releases (e.g., 1.0.1, 1.1.0) will be managed through this branch, which will receive bug fixes, performance improvements, and other necessary updates.

3. Development Branches (Feature Branches):

• Purpose: Feature branches will be created for the development and testing of new features or major changes before they are integrated into main.
• Naming Convention: Feature branches will be named descriptively, such as feature/cloudberrydb-1234, where 1234 refers to a specific issue or feature.
• Flow: Once the feature is stable and thoroughly tested, it will be merged into the main branch or an appropriate release branch.

4. Hotfix Branches:

• Purpose: Hotfix branches will be created to address critical bugs or security issues that arise after a release has been made.
• Naming Convention: Hotfix branches will follow a naming convention like hotfix/1.6.1-security.
• Flow: Once the hotfix is ready, it will be merged into both the release branch and main to ensure it is included in all future versions.

Semantic Versioning (SemVer):

• Adoption: The Cloudberry project will strictly adhere to SemVer, utilizing the MAJOR.MINOR.PATCH versioning format.
  Versioning Rules:
  • MAJOR: Increases when there are incompatible API changes.
  • MINOR: Increases when new features are added in a backward-compatible manner.
  • PATCH: Increases when backward-compatible bug fixes are applied.
• Tagging: All releases will be tagged according to SemVer (e.g., v1.0.0, v1.1.0, v2.0.0).

Rollout/Adoption Plan

1. Adopt the New Strategy:

• Transition the current branching structure to the PostgreSQL-style strategy with SemVer during the week of August 26.
• Create the initial REL_1_STABLE branch from main to manage the upcoming 1.0.0 release and all subsequent 1.x series updates.

2. Communicate to the Team:

• Ensure that all team members are informed of the new branching strategy and understand the importance of adhering to SemVer.
• Provide training or documentation as needed to facilitate the transition.

3. Update Documentation:

• Revise the project’s development documentation to reflect the new branching strategy, including guidelines for branch creation, merging, tagging, and versioning.
• Document the maintenance policy for release branches, specifying how long each release branch will be supported and maintained.

4. Monitor and Adjust:

• Monitor the effectiveness of the new strategy through feedback from the development team and users.
• Make adjustments as necessary to address any challenges or inefficiencies that arise during implementation.

5. Target Release:

• The initial Cloudberry 1.6.0 release is planned for September 3rd.

[leborchuk]

Sorry, a couple of questions about scheme implementation details:

1. Do not understand clearly, new release branch will be created from main branch?

2. How, precisely, will hotfixes be committed?

Release branch -- (fork) --> hotfix branch --> Release branch -- (cherry pick) --> main branch ?

or

Main branch -- (fork) --> hotfix branch --> Main branch -- (cherry pick) --> Release branch ?

or maybe more complicated scheme ...

3. Could release branch differ from main branch (contain commits not included in main)?

[edespino]

Sorry, a couple of questions about scheme implementation details:

1. Do not understand clearly, new release branch will be created from main branch?

We will create release branches from main. Ideally, main is in a releasable state at all times.

Features introducing binary incompatible changes (e.g. catalog change) will result in the MAJOR number changing
Features which are backward compatible will result in the MINOR number changing
Small updates and bugfixes will result in the PATCH number changing.

2. How, precisely, will hotfixes be committed?

Release branch -- (fork) --> hotfix branch --> Release branch -- (cherry pick) --> main branch ?

Hot fixes will be branched from release branches. The intent is to address critical issues with releases.

or

Main branch -- (fork) --> hotfix branch --> Main branch -- (cherry pick) --> Release branch ?

or maybe more complicated scheme ...

3. Could release branch differ from main branch (contain commits not included in main)?

Ideally any fixes addressed in release branches will be first committed to main and then cherry picked to the release branch.

Thank you very much for your questions.