Skip to content

Release Process Overview

Jump to bottom
Ed Espino edited this page Apr 20, 2025 · 17 revisions

Introduction

This page provides a high-level overview of the release process for Apache Cloudberry (Incubating). It outlines the steps involved in preparing, voting on, and publishing releases in accordance with ASF requirements.

Release Preparation

This section outlines the necessary steps and considerations before initiating a release of Apache Cloudberry (Incubating). Proper preparation ensures compliance with ASF policies and facilitates a smooth release process.

1. Establish Release Goals and Timeline

Before initiating a release, it's essential to define clear objectives and set a realistic timeline. This ensures alignment among contributors and stakeholders, facilitating a smooth release process.

Define Release Objectives

  • Scope Determination: Identify the features, enhancements, and bug fixes intended for the release.
  • Compliance Goals: Ensure all planned changes adhere to ASF policies and licensing requirements.
  • Quality Standards: Set criteria for testing, documentation, and code quality to be met before release.

Set a Realistic Timeline

  • Milestone Planning: Outline key phases such as code freeze, testing periods, and voting windows.
  • Resource Assessment: Evaluate the availability of contributors and adjust timelines accordingly.
  • Buffer Inclusion: Allocate extra time to accommodate unforeseen challenges or delays.

Communicate Plans

  • Documentation: Record the release goals and timeline in a shared document or tracking system.
  • Stakeholder Engagement: Share the plan with the community via mailing lists or meetings to gather feedback and ensure transparency.

2. Designate a Release Manager

Assigning a Release Manager (RM) is a critical step in orchestrating a successful release. The RM is responsible for coordinating the release process, ensuring compliance with ASF policies, and serving as the primary point of contact throughout the release cycle.

Responsibilities of the Release Manager

  • Coordinate Release Activities: Oversee the preparation, packaging, and distribution of the release artifacts.
  • Ensure Compliance: Verify that all release components adhere to ASF licensing and distribution policies.
  • Facilitate Communication: Act as the liaison between the development community and the PPMC, providing updates and addressing concerns.
  • Manage Voting Process: Initiate and manage the voting process for the release, ensuring that all necessary approvals are obtained from the PPMC and IPMC.
  • Handle Release Artifacts: Sign the release artifacts and upload them to the appropriate ASF distribution channels.

Selecting a Release Manager

  • Community Consensus: The RM should be selected through consensus within the community, typically involving a discussion and agreement on the development mailing list.
  • Committer Status: The RM must be a committer with the necessary permissions to manage and publish release artifacts.
  • Experience and Familiarity: Ideally, the RM should have experience with the project's release process and be familiar with ASF policies and procedures.

Best Practices

  • Documentation: Maintain clear documentation of the release process to assist current and future RMs.
  • Mentorship: Encourage experienced RMs to mentor new volunteers, fostering knowledge transfer and community growth.
  • Rotation: Consider rotating the RM role among qualified community members to distribute knowledge and responsibilities.

3. Review and Finalize Codebase

Before initiating a release, it's crucial to ensure that the codebase is stable, compliant, and ready for distribution. This involves thorough reviews, testing, and final adjustments to meet the project's quality standards and ASF policies.

Code Review and Quality Assurance

  • Comprehensive Code Reviews: Ensure that all recent changes have been reviewed and approved by qualified committers. Focus on code correctness, clarity, and adherence to project standards.
  • Testing: Verify that all unit, integration, and system tests pass consistently. Address any flaky or failing tests.
  • Static Analysis: Utilize tools like linters or static analyzers to detect potential issues in the codebase.

Dependency and License Verification

  • Dependency Audit: Review all project dependencies to ensure they are up-to-date and compatible with the Apache License. Remove or replace any dependencies with incompatible licenses.
  • License Compliance: Confirm that all source files contain the appropriate ASF license headers and that the LICENSE and NOTICE files are accurate and complete.

Final Preparations

  • Documentation: Update README files, user guides, and other relevant documentation to reflect the upcoming release.
  • Versioning: Ensure that version numbers are correctly set throughout the codebase, including in configuration files and documentation.
  • Cleanup: Remove any deprecated code, unused files, or temporary artifacts that are not intended for the release.

By meticulously reviewing and finalizing the codebase, the project ensures a high-quality release that aligns with ASF standards and provides value to the community.

4. Update Documentation

Ensuring that all documentation is accurate and up-to-date is a critical step in the release process. Comprehensive and current documentation enhances user experience and facilitates adoption of the new release.

Review Existing Documentation

  • User Guides and Manuals: Verify that all user-facing documents reflect the latest features, configurations, and usage instructions.
  • API References: Ensure that all API documentation is updated to match any changes or additions made in the release.
  • Installation Instructions: Confirm that setup guides are accurate and include any new dependencies or configuration steps.

Update Release-Specific Documents

  • Changelog: Compile a list of all significant changes, enhancements, and bug fixes included in the release.
  • Migration Guides: Provide clear instructions for users upgrading from previous versions, highlighting any breaking changes or deprecated features.
  • FAQ and Troubleshooting: Update common questions and solutions to address new features or known issues in the release.

Documentation Accessibility

  • Format Consistency: Maintain a consistent format and style across all documentation to ensure readability.
  • Localization: If applicable, update translations of documentation to include new content.
  • Publishing: Ensure that all updated documents are published to the appropriate platforms, such as the project's website, repositories, or documentation portals.

By thoroughly updating documentation, the project ensures that users and contributors have the necessary information to effectively utilize and support the new release.

5. Verify Licensing and Dependencies

Ensuring that all code and dependencies comply with ASF licensing policies is a critical step in the release process. This verification helps maintain the project's integrity and legal standing.

Review Project Dependencies

  • Audit Dependencies: Compile a list of all project dependencies, including direct and transitive ones.
  • License Compatibility: Verify that each dependency's license is compatible with the Apache License 2.0.
  • Update or Replace: For any dependencies with incompatible licenses, consider updating to a compatible version or replacing them with alternatives.

Run Apache RAT (Release Audit Tool)

  • Execute RAT: Use the Apache RAT tool to scan the codebase for license compliance.
  • Identify Issues: Review the RAT report to identify files lacking proper license headers or containing incompatible licenses.
  • Remediate Findings: Add missing license headers and address any other issues highlighted by the RAT report.

Update Licensing Documentation

  • LICENSE File: Ensure the LICENSE file accurately reflects the project's licensing terms and includes all necessary notices.
  • NOTICE File: Update the NOTICE file to include attributions for bundled third-party components, as required.
  • Third-Party Notices: If applicable, include a separate file detailing third-party notices and attributions.

By thoroughly verifying licensing and dependencies, the project upholds ASF standards and fosters trust within the community.

6. Prepare Release Notes

Release notes provide users and contributors with a summary of the changes, enhancements, and fixes included in the new release. They serve as an essential communication tool, highlighting the evolution of the project and informing stakeholders of important updates.

Compile Notable Changes

  • New Features: List significant features added since the previous release.
  • Enhancements: Describe improvements made to existing functionalities.
  • Bug Fixes: Summarize resolved issues and defects.
  • Deprecations and Removals: Note any deprecated features or APIs, and provide guidance on alternatives.

Structure the Release Notes

  • Introduction: Provide a brief overview of the release, including its purpose and scope.
  • Change Log: Present a categorized list of changes, grouped by type (e.g., Features, Bug Fixes).
  • Upgrade Instructions: Offer guidance on how to upgrade from previous versions, including any necessary steps or precautions.
  • Acknowledgments: Recognize contributors who have played a significant role in the release.

Best Practices

  • Clarity and Conciseness: Write clear and concise descriptions to ensure readability.
  • Consistency: Maintain a consistent format and style across releases.
  • Accessibility: Publish the release notes in accessible locations, such as the project's website, repository, and mailing lists.

By preparing comprehensive and well-structured release notes, the project enhances transparency and facilitates user adoption of the new release.

7. Set Version Numbers

Proper versioning is essential for tracking releases, ensuring compatibility, and communicating changes to users. Apache Cloudberry (Incubating) follows Semantic Versioning (SemVer) to maintain consistency and clarity.

Semantic Versioning Format

  • Major: Increments for incompatible API changes.
  • Minor: Increments for added functionality in a backward-compatible manner.
  • Patch: Increments for backward-compatible bug fixes.

For example, version 2.0.0 indicates a major release with potential breaking changes.

Updating Version Numbers

  1. Determine the Next Version: Based on the nature of changes, decide whether to increment the major, minor, or patch version.

  2. Update Configuration Files:

    • Modify the version number in configure.ac:

      AC_INIT([Cloudberry Database], [2.0.0], [[email protected]], [], [https://www.cloudberrydb.org/])

    • Update the VERSION file, if present, with the new version number.

  3. Regenerate Configuration Scripts: After updating configure.ac, regenerate the configure script:

    autoreconf -i

  4. Commit Changes:

    git add configure.ac VERSION configure
git commit -m "Set version number to 2.0.0 for upcoming release"

  5. Tag the Release: Create an annotated tag for the release:

    git tag -a v2.0.0 -m "Apache Cloudberry (Incubating) 2.0.0 Release"
git push origin v2.0.0

Best Practices

  • Consistency: Ensure all references to the version number across documentation and configuration files are updated.
  • Pre-release Identifiers: For alpha, beta, or release candidates, append identifiers like -alpha, -beta, or -rc (e.g., 2.0.0-rc1).
  • Post-Release: After the release, increment the version number in the development branch to the next snapshot (e.g., 2.1.0-SNAPSHOT) to indicate ongoing development.

By adhering to these practices, Apache Cloudberry maintains clear versioning, aiding users and contributors in understanding the progression and compatibility of releases.

8. Release Candidate Creation

Creating a Release Candidate (RC) is a crucial step in the Apache release process. It involves preparing a version of the software that is intended for final testing and verification before the official release.

Steps to Create a Release Candidate

  1. Prepare the Release Artifacts:

    • Ensure that the codebase is stable and all tests pass.
    • Generate the source release package, ensuring it includes all necessary files and documentation.
    • Sign the release artifacts using your Apache GPG key.

  2. Upload to the Development Repository:

    • Upload the signed release artifacts to the project's development area on https://dist.apache.org/repos/dist/dev/

  3. Announce the Release Candidate:

    • Send an email to the project's development mailing list announcing the availability of the RC.
    • Include details about the RC, such as version number, changes since the last release, and instructions for testing.

  4. Initiate the Voting Process:

    • Start a [VOTE] thread on the development mailing list to gather feedback and approval from the community.
    • The voting period should last at least 72 hours.

By following these steps, the project ensures that the release candidate is thoroughly vetted and ready for the final release.

9. Community Testing

Engaging the community in testing the release candidate is vital to ensure the quality and stability of the upcoming release. Community testing helps identify issues that may not have been caught during internal testing and provides valuable feedback from diverse environments and use cases.

Objectives of Community Testing

  • Validate Functionality: Ensure that new features work as intended and existing functionalities remain unaffected.
  • Identify Bugs: Detect and document any defects or regressions.
  • Assess Compatibility: Verify that the release candidate works across different environments and configurations.
  • Gather Feedback: Collect suggestions for improvements and enhancements.

Organizing Community Testing

  1. Announce the Testing Phase:

    • Send an email to the project's development mailing list announcing the availability of the release candidate for testing.
    • Provide details about the release candidate, including download links, installation instructions, and a summary of changes.

  2. Provide Testing Guidelines:

    • Offer a checklist or guide outlining areas to focus on during testing.
    • Encourage testers to report issues with clear reproduction steps and logs.

  3. Facilitate Communication:

    • Set up channels (e.g., mailing lists, chat rooms) for testers to discuss findings and ask questions.
    • Monitor these channels to provide support and gather feedback.

  4. Document Reported Issues:

    • Track reported bugs and feedback in the project's issue tracker.
    • Prioritize and address critical issues before proceeding to the voting phase.

Encouraging Participation

  • Acknowledge Contributions: Recognize and thank community members who participate in testing.
  • Lower Barriers: Make it easy for contributors to get involved by providing clear instructions and support.
  • Highlight Impact: Emphasize how community testing contributes to the project's success and quality.

By actively involving the community in testing, the project benefits from diverse perspectives and environments, leading to a more robust and reliable release.

Voting Process

Content coming soon.

Post-Release Activities

Content coming soon.

Clone this wiki locally