feat(releasekit): add Forge protocol extensions, transitive propagation, and multi-backend conformance

[yesudeep]

Summary

Extends the releasekit Forge and VCS protocols with new operations needed for the release-please model, adds three new backend implementations to validate protocol generality, implements transitive version propagation, and adds granular exclusion controls with PyPI metadata compliance.

Changes

Forge protocol extensions

• list_prs: find PRs by label/state/head (for tag step)
• add_labels / remove_labels: manage autorelease labels
• update_pr: update Release PR body with embedded manifest

New backends

• GitHubCLIBackend — uses gh
• GitLabCLIBackend — uses glab
• BitbucketAPIBackend — uses httpx
• GitCLIBackend — uses git
• MercurialCLIBackend — uses hg

Naming convention

CLI-based backends use CLIBackend suffix, REST API-based use APIBackend. Makes future GitHubAPIBackend unambiguous alongside GitHubCLIBackend.

Versioning

• BFS transitive PATCH propagation via dependency graph (deque-based, handles multi-level chains)
• Synchronized versioning (synchronize=True) for lockstep releases
• synchronize field added to ReleaseConfig (default False)

Exclusion hierarchy

Three levels of exclusion control how much of the pipeline a package participates in:

Level	Discovered	Checked	Version-bumped	Published
(normal)	✅	✅	✅	✅
exclude_publish	✅	✅	✅	❌
exclude_bump	✅	✅	❌	❌
exclude	❌	❌	❌	❌

Group references with group:<name> syntax

All exclude lists support group:<name> references that recursively expand to group patterns. Cycle detection prevents infinite loops.

[groups]
google_plugins = ["genkit-plugin-firebase", "genkit-plugin-google-*"]
community_plugins = ["genkit-plugin-anthropic", "genkit-plugin-ollama"]
all_plugins = ["group:google_plugins", "group:community_plugins"]

exclude_publish = ["group:samples", "genkit-plugin-xai"]

New health checks (17 total, up from 10)

• python_version — consistent requires-python across packages
• python_classifiers — Python version classifiers (3.10–3.14)
• dependency_resolution — uv pip check passes
• namespace_init — no __init__.py in namespace directories
• readme_field — publishable packages declare readme in [project]
• changelog_url — publishable packages have Changelog in [project.urls]
• publish_classifier_consistency — exclude_publish agrees with Private :: Do Not Upload classifier

PyPI metadata improvements (all packages + plugins)

• Added Framework :: AsyncIO classifier
• Added Framework :: Pydantic classifier
• Added Framework :: Pydantic :: 2 classifier
• Added Changelog URL to [project.urls] for all 14 publishable packages
• Added Private :: Do Not Upload classifier to all 39 samples and 8 unreleased plugins

Code cleanup

• Removed section marker comments per GEMINI.md
• Moved in-function imports to top-level
• Converted asyncio.get_event_loop() to @pytest.mark.asyncio
• Added .releasekit-state.json and release-manifest.json to .gitignore

README updates

• Expanded "Why This Tool Exists" with uv publish vs releasekit comparison table
• Documented exclusion hierarchy and group: reference syntax
• Updated health checks list from 10 to 17
• Added configuration options for exclude_publish and exclude_bump

Tests

• 41 new tests (protocol conformance, backend-specific)
• All 524 tests pass
• 17/17 health checks pass
• Lint and format clean

[gemini-code-assist]

Summary of Changes

Hello @yesudeep, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the releasekit tool by expanding its compatibility with various code hosting platforms and version control systems. It introduces new capabilities for managing pull requests and implements advanced versioning strategies, including transitive dependency propagation and synchronized lockstep releases. These changes aim to make releasekit more robust and adaptable to diverse release-please models, ensuring broader applicability and maintainability.

Highlights

• Forge Protocol Extensions: Extended the Forge protocol with new operations: list_prs to find PRs by label/state/head, add_labels and remove_labels for managing autorelease labels, and update_pr to modify PR titles and bodies.
• New Backend Implementations: Introduced three new backend implementations to validate protocol generality: BitbucketAPIBackend for Forge operations via REST API, GitLabCLIBackend for Forge operations via glab CLI, and MercurialCLIBackend for VCS operations via hg CLI. The existing GitHub and Git backends were renamed to GitHubCLIBackend and GitCLIBackend for consistent naming.
• Transitive Version Propagation: Implemented BFS-based transitive PATCH propagation for independent versioning, ensuring that if a package is bumped, all its downstream internal dependents also receive a PATCH bump to keep lockfiles fresh.
• Synchronized Versioning Mode: Added a new synchronize configuration option to enable lockstep versioning, where all packages in the workspace receive the maximum bump computed across the entire workspace.
• Code Cleanup and Testing: Performed code cleanup by removing section marker comments and moving in-function imports to top-level. Added 41 new tests, including comprehensive protocol conformance tests for all new and existing backends, ensuring all 524 tests pass.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• py/tools/releasekit/roadmap.md
  • Updated Phase 5 status to 'In progress' and detailed completion status for Forge extensions, versioning propagation, and new backends.
  • Added a new 'TODO: Eng docs' section outlining future documentation needs for backend comparison tables and protocol design rationale.
• py/tools/releasekit/src/releasekit/backends/init.py
  • Updated default VCS backend from GitBackend to GitCLIBackend.
  • Updated default Forge backend from GitHubBackend to GitHubCLIBackend.
  • Renamed GitBackend to GitCLIBackend and GitHubBackend to GitHubCLIBackend in __all__ export list.
• py/tools/releasekit/src/releasekit/backends/bitbucket.py
  • Added new file bitbucket.py implementing BitbucketAPIBackend for Forge protocol using Bitbucket REST API v2.0 via httpx.
  • Included methods for create_release, delete_release, promote_release, list_releases, create_pr, pr_data, list_prs, add_labels, remove_labels, and update_pr.
• py/tools/releasekit/src/releasekit/backends/forge.py
  • Updated documentation to refer to GitHubCLIBackend as the default Forge implementation.
  • Extended the Forge protocol with abstract methods for list_prs, add_labels, remove_labels, and update_pr.
  • Renamed GitHubBackend class to GitHubCLIBackend.
  • Updated pr_data method in GitHubCLIBackend to fetch additional PR fields (headRefName, mergeCommit).
  • Implemented list_prs, add_labels, remove_labels, and update_pr methods in GitHubCLIBackend using gh CLI commands.
• py/tools/releasekit/src/releasekit/backends/gitlab.py
  • Added new file gitlab.py implementing GitLabCLIBackend for Forge protocol using glab CLI.
  • Included methods for create_release, delete_release, promote_release, list_releases, create_pr, pr_data, list_prs, add_labels, remove_labels, and update_pr.
• py/tools/releasekit/src/releasekit/backends/mercurial.py
  • Added new file mercurial.py implementing MercurialCLIBackend for VCS protocol using hg CLI.
  • Included methods for is_clean, is_shallow, current_sha, log, diff_files, commit, tag, tag_exists, delete_tag, push, and checkout_branch.
• py/tools/releasekit/src/releasekit/backends/vcs.py
  • Updated documentation to refer to GitCLIBackend as the default VCS implementation.
  • Renamed GitBackend class to GitCLIBackend.
  • Updated __all__ export list to reflect the GitCLIBackend rename.
• py/tools/releasekit/src/releasekit/checks.py
  • Removed several section marker comments (e.g., 'CheckBackend protocol', 'Universal checks', 'PythonCheckBackend', 'run_checks').
• py/tools/releasekit/src/releasekit/cli.py
  • Updated imports to use GitHubCLIBackend and GitCLIBackend instead of GitHubBackend and GitBackend.
  • Modified _create_backends function signature and implementation to instantiate GitCLIBackend and GitHubCLIBackend.
• py/tools/releasekit/src/releasekit/config.py
  • Added synchronize field to _KNOWN_CONFIG_KEYS.
  • Added synchronize attribute to ReleaseConfig dataclass, defaulting to False, to control lockstep versioning.
• py/tools/releasekit/src/releasekit/versioning.py
  • Imported deque from collections and DependencyGraph from releasekit.graph.
  • Modified compute_bumps function signature to accept graph and synchronize parameters.
  • Updated compute_bumps to implement a two-phase process: first, direct bumps from commits, then propagation based on synchronize flag or dependency graph.
  • Implemented BFS-based transitive PATCH propagation for independent versioning when a graph is provided.
  • Implemented synchronized (lockstep) versioning logic where all packages receive the maximum bump across the workspace if synchronize is True.
• py/tools/releasekit/tests/backends/rk_forge_test.py
  • Renamed TestGitHubBackendProtocol to TestGitHubCLIBackendProtocol and updated GitHubBackend to GitHubCLIBackend.
  • Renamed TestGitHubBackendDryRun to TestGitHubCLIBackendDryRun and updated GitHubBackend to GitHubCLIBackend.
  • Added new test cases for add_labels, remove_labels, and update_pr dry-run functionality in GitHubCLIBackend.
• py/tools/releasekit/tests/backends/rk_protocol_conformance_test.py
  • Added new file rk_protocol_conformance_test.py to verify protocol conformance for all Forge and VCS backends.
  • Included TestForgeProtocolConformance with tests for GitHubCLIBackend, GitLabCLIBackend, and BitbucketAPIBackend.
  • Included TestForgeDryRunConformance with parametrized tests for create_release, delete_release, create_pr, add_labels, remove_labels, and update_pr across all Forge backends.
  • Included TestVCSProtocolConformance with tests for GitCLIBackend and MercurialCLIBackend.
  • Included TestVCSDryRunConformance with parametrized tests for is_clean, commit, tag, delete_tag, push, and checkout_branch across all VCS backends.
  • Added TestMercurialSpecifics for Mercurial-specific behavior like is_shallow always returning False and push mapping 'origin' to 'default'.
  • Added TestBitbucketSpecifics for Bitbucket-specific behavior like authentication requirements and add_labels/remove_labels being no-ops.
• py/tools/releasekit/tests/backends/rk_vcs_test.py
  • Updated _init_repo function to return GitCLIBackend.
  • Renamed TestGitBackendProtocol to TestGitCLIBackendProtocol and updated GitBackend to GitCLIBackend.
  • Renamed TestGitBackendIsClean to TestGitCLIBackendIsClean.
  • Renamed TestGitBackendIsShallow to TestGitCLIBackendIsShallow.
  • Renamed TestGitBackendCurrentSha to TestGitCLIBackendCurrentSha.
  • Renamed TestGitBackendLog to TestGitCLIBackendLog.
  • Renamed TestGitBackendCommit to TestGitCLIBackendCommit.
  • Renamed TestGitBackendTag to TestGitCLIBackendTag.
• py/tools/releasekit/tests/rk_versioning_test.py
  • Imported build_graph from releasekit.graph.
  • Added TestTransitivePropagation class with tests for direct and multi-level transitive PATCH propagation via dependency graphs.
  • Added TestSynchronizedMode class with tests for lockstep versioning, ensuring all packages receive the maximum bump and correct reasons.

Activity

• The pull request introduces significant new features and refactorings across the releasekit tool.
• New backend implementations for Bitbucket, GitLab, and Mercurial have been added, alongside extensions to the Forge protocol.
• Versioning logic has been enhanced with transitive propagation and synchronized modes.
• Comprehensive test coverage has been added for the new backends and versioning features, with all existing tests passing.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request significantly expands the capabilities of releasekit by introducing a more generic protocol for Forges and VCS systems, and adding multiple new backend implementations (GitLab, Bitbucket, Mercurial). The introduction of transitive version propagation and synchronized versioning adds valuable new features for managing complex monorepos. The code is well-structured, and the addition of protocol conformance tests is a great step towards ensuring robustness and maintainability.

I have two suggestions for improvement: one regarding an inefficiency in the new BitbucketAPIBackend and another to fix a type mismatch in the GitLabCLIBackend.

[yesudeep]

/gemini review

[gemini-code-assist]

Code Review

This is an impressive and substantial pull request that introduces a powerful new release orchestration tool, releasekit. The changes are extensive, well-structured, and demonstrate a deep understanding of release engineering challenges across multiple ecosystems. The move to a protocol-based backend system is excellent for testability and future extensibility. The detailed configuration options, transitive dependency propagation, and comprehensive health checks are all great features. The documentation updates in the README and roadmap are also very thorough. I've found a couple of security-related improvement opportunities in the GitHub Action workflow file, but overall this is a very high-quality contribution.

[yesudeep]

/gemini review

[gemini-code-assist]

Code Review

This is an extensive and well-executed pull request that significantly enhances the releasekit tool. The introduction of a protocol-based backend system for VCS, forges, package managers, and registries is a fantastic design choice that makes the tool highly extensible and testable. The addition of backends for GitLab, Bitbucket, Mercurial, and pnpm demonstrates the power of this new architecture.

The new features, including transitive version propagation, synchronized versioning, granular exclusion controls, and group-based releases, are powerful and well-implemented. The move to a dedicated releasekit.toml configuration file is a smart decision for a polyglot tool.

The attention to detail is evident throughout, from the security-conscious GitHub Action implementation to the comprehensive updates to documentation and the addition of numerous health checks. The code quality is excellent, and the new test suite provides good coverage for the new functionality. This is a high-quality contribution that greatly expands the capabilities of the release tool.