[Feat]: Proposal - Establish Predictable Documentation and Release Cadence for Main Branch

# A2A Protocol - Release Management Proposal for Docs and Protocol

**Executive Summary**: This proposal outlines a refined release management
strategy for the A2A protocol and its accompanying documentation site. By
transitioning to a structured two-branch model and a predictable documentation
update cycle, we aim to improve stability for the developer community, reduce
manual maintenance overhead, and ensure that documentation changes are
predictable.

## 1. Introduction & Objectives

The A2A protocol and its documentation are critical resources for our
developers. As the protocol evolves towards major versions (v1, v2.2, v3.0,
v4.0), our current management process faces scalability challenges. The primary
objectives of this proposal are:

- **Predictability**: Ensure users know when to expect documentation updates.
- **Conflict Reduction**: Minimize branch conflicts and manual labor (e.g.,
cherry-picking).
- **Version Isolation**: Separate stable patch fixes from long-term breaking
changes.

## 2. Problem Statement & Challenges

The A2A protocol and its documentation are currently facing scalability and
predictability issues that hinder effective collaboration and user experience:

- **Documentation Unpredictability**: Currently, changes merged to the main
branch render immediately. This makes documentation updates unpredictable for
users and provides no window for final verification.
- **Complex Patch Management**: Managing direct changes to protocol
specifications alongside critical resources like Protobufs and JSON files is
difficult within a single branch.
- **No.Branch Management for Future Versions**: Long-term feature
planning (e.g., v3.0, v4.0) often involves breaking changes. Without a
dedicated development branch, these cannot be integrated without disrupting
the stable main branch.

## 3. Proposed Solution: The Two-Branch Model

We propose a simplified branching strategy combined with a scheduled release
cycle to ensure stability and predictability.

### 3.1 Branching Strategy

- **Main Branch**: Used for bug fixes, stable patch fixes, and standard
documentation updates.
- **Developer Branch(s)**: Reserved for breaking changes and development of
future protocol versions.

If we have a semantic version number as MAJOR.MINOR.PATCH, then:

1. All PATCH versions updates are added to **main** branch
1. All MAJOR version & MINOR version updates will be part of **feature**
branch(s)

### 3.2 Scheduled Documentation Release

- Instead of immediate rendering, documentation will be updated on a fixed
schedule (e.g., Tuesday mornings or Fridays). This allows the TSC to review
changes and ensures users build "muscle memory" for when to expect updates.

## 4. Alternative Solutions Considered
We evaluated several branching models and workflows before proposing the
Two-Branch model. Below are the details for each alternative, including the
current state.

### 4.1 Single Branch Model (Current Style)

This is the existing approach where all changes—whether bug fixes, documentation
tweaks, or new features—are merged directly into the `main` branch.

- **Advantages**: Extremely simple; no overhead from branch synchronization or
complex merging strategies.
- **Disadvantages**:
- Breaking feature PRs remain unmerged for extended periods because they
cannot be safely added to the stable branch.
- Stale, unmerged PRs give the repository an "unhealthy" look and hinder
visibility into active development.
- Documentation rendering is unpredictable and immediate, providing no buffer
for TSC verification.

### 4.2 Dedicated Documentation Branch + Main Branch

In this model, the `main` branch contains all code and specifications, while a
separate `documentation` branch is used exclusively for rendering the site.

- **Advantages**: Provides a clear separation between the codebase and the
documentation site.
- **Disadvantages**: Requires intensive manual effort. Non-breaking
documentation and patch fixes merged to `main` must be manually cherry-picked
into the documentation branch. This process is labor-intensive and prone to
human error.

### 4.3 Three-Branch Model (Main, Doc, Dev)

This approach uses three dedicated branches for production (`main`),
documentation (`doc`), and future development (`dev`).

- **Advantages**: Offers the highest level of isolation for different types of
work (stable vs. doc vs. experimental).
- **Disadvantages**: Significantly increases the merge burden. Every update to
`main` must be merged into both `doc` and `dev` branches, leading to a much
higher frequency of merge conflicts and doubling the manual maintenance
workload.

## 5. Implementation Benefits

- **Reduced Conflicts**: Fewer branches compared to a three-branch model
simplifies merging and reduces technical debt.
- **Operational Efficiency**: Eliminates the need for manual cherry-picking of
non-breaking changes from main to other branches.
- **Improved Communication**: Provides a clear framework for communicating
changes to the developer community and internal maintenance teams.

## 6. Naming Conventions and Standards

- **Stable Branch**: The primary branch will remain `main`.
- **Documentation Hosting**: Static site deployments will continue to use the
`gh-pages` branch.
- **Feature Branches**: Development branches for future versions will follow the
naming format `dev_X.Y`, where X and Y represent the major and minor versions
respectively.

## 7. Implementation Plan

- Update the A2A contributor guidelines to reflect the new branching and release
strategy.
- Initialize feature branches for upcoming major and minor version development.
- Revise Pull Request templates to ensure clear distinction between patch fixes
and feature releases.
- Integrate links to the A2A Discord channel for real-time team coordination
to support on Minor and Major PR
- (Stretch 1) Deploy GitHub Actions for automated branch name pattern validation
to enforce repository structure standards.
- (Stretch 2) Deploy GitHub Actions for automatic PRs to merge the main branch
into dev branches that follow the dev underscore pattern on a bi-weekly basis
- (Stretch 3) Update the Github Actions to update A2A docs site at regular
intervals(Fridays).

---------
Below is the initial draft created!

### Is your feature request related to a problem? Please describe.

Yes. Currently, our protocol documentation is updated almost regularly as new PRs are merged. While it's great that we are moving fast, users who are learning the protocol will experience a shifting landscape. This can makes the system feel unstable and unreliable to end-users trying to build on top of our specs.

Additionally, we face a workflow challenge: if we have a great breaking feature ready mid-month that belongs in the next version or v2.0, we struggle to merge it without it immediately appearing in the live documentation and causing confusion before the official release.

### Describe the solution you'd like

Draft Proposal: Stable Documentation Cuts

1. **Decouple live docs from the working branch**: The live, user-facing documentation should point exclusively to the **latest stable release branch** (e.g., v1.0), not the bleeding-edge main branch.

1. **Predictable Release Schedule**: We update the live documentation on a specific, predictable cadence (e.g., the last Friday or second-to-last Tuesday of the month) alongside our semantic versioning releases.
> Note: Any changes to Spec will be visible only after docs update.

1. **Branching for Releases**: When a new stable version is ready (e.g., v1.1), we cut a fresh branch from main and update the documentation pointer to this new stable branch.

### Describe alternatives you've considered

We have two main approaches for handling this:

* Option 1: Continuous Updates (Current approach)

* Concept: Push branches straight to main and keep the live documentation continuously up to date every time a PR merges.

* Drawback: Highly unpredictable for users, makes the protocol feel unstable, and risks exposing unreleased breaking features to users too early.

* Option 2: Strict Stable Cuts (Proposed approach)

* Concept: Maintain a stable version of the documentation that only updates when we cut a new release branch at the end of our release cycle.

* Drawback: Fixes and new features are delayed from the public docs until the official release day (though this is standard practice for most major frameworks).

### Additional context

Implementing this will heavily improve our semantic versioning strategy.

For example, if we merge a breaking feature mid-month, we can safely keep it in the main development branch. We won't have to worry about it prematurely showing up in the stable v1.0 user documentation before the official v1.1 release at the end of the month. Predictability is key for developer adoption!

### Code of Conduct

- [x] I agree to follow this project's Code of Conduct