-
Notifications
You must be signed in to change notification settings - Fork 152
Release Process Overview
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.
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.
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.
- 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.
- 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.
- 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.
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.
- 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.
- 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.
- 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.
To improve transparency and community coordination during releases, the Apache Cloudberry (Incubating) project is experimenting with the use of GitHub Project boards to organize release-related work.
GitHub Projects provide a shared, visual way to track all release deliverables and tasks, including:
- Proposed and prioritized PRs
- Packaging and convenience binary tasks
- Testing and verification work
- Vote coordination and post-release activities
The board supplements, but does not replace, Apache’s official release requirements and email-driven decision making.
A dedicated project board has been created for the 2.0.0 release:
GitHub Project: https://github.com/orgs/apache/projects/490
This board is structured with the following columns:
- Scope & Planning – Goals, coordination, and planning threads
- Candidate PRs – PRs proposed for inclusion
- In Progress – Tasks being actively worked on
- Awaiting Feedback – Tasks pending review or testing
- Ready for RC – Items finalized for release candidate preparation
- Vote in Progress – Release voting in motion
- Post-Release Tasks – Website updates, announcements, packaging
- Done – Items that are completed and closed
- This project board is a community coordination tool, not a substitute for ASF processes.
- All official release decisions, including release approvals and voting, must occur via the
[email protected]and[email protected]mailing lists, per ASF Incubator policy. - Only source code releases voted on by the PPMC and IPMC are considered official ASF releases.
- Convenience binaries (e.g., RPMs,
.deb, Docker images) may be tracked here, but are published separately and clearly labeled as such.
This use of GitHub Projects may evolve as the community gains experience and as we move toward graduation from the Apache Incubator.
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.
- 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 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.
- 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.
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.
- 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.
- 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.
- 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.
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.
- 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.
- 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.
- 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.
-
DISCLAIMER File: All source releases must include a
DISCLAIMERorDISCLAIMER-WIPfile to indicate the project's incubation status, as required by the ASF Incubator policy.
By thoroughly verifying licensing and dependencies, the project upholds ASF standards and fosters trust within the community.
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.
- 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.
- 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.
- 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.
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.
- 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.
-
Determine the Next Version: Based on the nature of changes, decide whether to increment the major, minor, or patch version.
-
Update Configuration Files:
- Modify the version number in
configure.ac:AC_INIT([Apache Cloudberry], [2.0.0], [[email protected]], [], [https://cloudberry.apache.org/])
- Update the
VERSIONfile, if present, with the new version number.
If the new release is a major release, you also need to change the version number in the file
gpMgmt/bin/gppylib/gpversion.py:MAIN_VERSION = [2,99] - Modify the version number in
-
Regenerate Configuration Scripts: After updating
configure.ac, regenerate theconfigurescript:autoreconf -i
-
Commit Changes:
git add configure.ac VERSION configure git commit -m "Set version number to 2.0.0 for upcoming release" -
Tag the Release: Create an annotated tag for the release:
git tag -a v2.0.0-incubating -m "Apache Cloudberry (Incubating) 2.0.0 Release" git push origin v2.0.0-incubating
- 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. -
Incubating Labeling: All artifact filenames must include the word
incubating(e.g.,apache-cloudberry-incubating-2.0.0-src.tar.gz).
By adhering to these practices, Apache Cloudberry maintains clear versioning, aiding users and contributors in understanding the progression and compatibility of releases.
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.
-
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.
-
Upload to the Development Repository:
- Upload the signed release artifacts to the project's development area on
https://dist.apache.org/repos/dist/dev/
- Upload the signed release artifacts to the project's development area on
-
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.
-
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.
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.
- 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.
-
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.
-
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.
-
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.
-
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.
- 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.
The voting process is a critical step in the Apache release cycle, ensuring that the release candidate has been thoroughly reviewed and approved by the community. This process involves a formal vote by the Podling Project Management Committee (PPMC) and subsequently the Incubator Project Management Committee (IPMC), which holds binding authority during incubation.
-
Call for Vote: The Release Manager sends an email to the project's development mailing list with the subject line
[VOTE] Release Apache Cloudberry (Incubating) x.y.z. This email should include:- Links to the release artifacts.
- Instructions for verifying the release.
- The duration of the voting period (minimum of 72 hours).
- Voting Period: The vote must remain open for at least 72 hours to allow all community members to participate, regardless of their time zone.
-
Vote Types:
-
+1: Approve the release. -
+0: No opinion. -
-1: Disapprove the release (must include a technical justification).
-
-
Binding Votes:
- In the first phase, only PPMC members' votes are binding.
- If the PPMC vote passes, the RM must start a second vote on
[email protected]. - In the second phase, only votes from IPMC members are binding.
-
Vote Outcome:
- At least three binding
+1votes are required. - The number of binding
+1votes must exceed the number of binding-1votes. - Releases cannot be vetoed; however, significant issues raised during the vote may lead to the cancellation of the release candidate.
- At least three binding
-
Announce Results: After the voting period concludes, the Release Manager sends an email to the development mailing list with the subject line
[VOTE][RESULT] Release Apache Cloudberry (Incubating) x.y.z. This email should summarize the voting results, including:- The number of
+1,+0, and-1votes. - Identification of binding votes.
- Any issues raised during the voting process.
- The number of
By following this structured voting process, the project ensures that each release is vetted and approved by the community, maintaining the integrity and quality of the software.
After a successful vote and the release of Apache Cloudberry (Incubating) version x.y.z, several post-release tasks should be performed to ensure proper dissemination and documentation.
-
Development Mailing List: Send an announcement to the
[email protected]mailing list summarizing the release. -
General Announcement: If appropriate, send an announcement to
[email protected]. Ensure that the email is sent from an@apache.orgaddress, as required.
- Download Page: Update the project's download page to include links to the new release artifacts.
- Release Notes: Add the release notes for version x.y.z to the website.
- Documentation: Ensure that any version-specific documentation is updated accordingly.
- Close Resolved Issues: Ensure that all issues resolved in this release are closed.
- Update Versions: Mark version x.y.z as released in the issue tracker.
- Create New Version: Create a new version entry for the next planned release.
-
Create Git Tag: Tag the release in the version control system with a tag like
vX.Y.Z. - Push Tag: Push the tag to the remote repository.
- Move Old Artifacts: Move previous release artifacts to the archive directory, if applicable.
- Update Links: Ensure that links to old releases are updated to point to the archive location.
- Increment Version: Update the version number in the codebase to the next snapshot version (e.g., x.y.z+1-SNAPSHOT).
- Update Documentation: Begin updating documentation to reflect ongoing development.
By completing these post-release activities, the project maintains clarity and ensures that users and contributors have access to the latest information and resources.