Build & Release Process
Relevant source files
The following files were used as context for generating this wiki page:
The Build & Release process for the SuperGemini Framework is a multi-stage workflow designed to ensure the delivery of high-quality, secure, and stable Python packages to PyPI and GitHub. This process encompasses automated testing, semantic versioning, multi-platform validation, and security scanning to maintain the integrity of the framework.
The framework utilizes a combination of local validation scripts and GitHub Actions for continuous integration and delivery. While primarily a Python-based project, the ecosystem also includes an NPM wrapper package (@superclaude-org/supergemini) to facilitate installation for Node.js users. Sources: PUBLISHING.md:3-12, CLAUDE.md:281-285
Release Workflow Overview
The release cycle follows a structured path from development to production, moving through pre-publication testing and quality gates.
The diagram above illustrates the standard lifecycle of a SuperGemini release from initial development to final PyPI publication.
Sources: PUBLISHING.md:5-12
Publication Channels
| Channel | Purpose | Command / Tool |
|---|---|---|
| PyPI | Primary distribution for users | pip install SuperGemini |
| NPM | Alternative for Node.js environments | npm install -g superclaude |
| GitHub | Development versions and source | `pip install git+https://github.com/...%60 |
| TestPyPI | Pre-production validation | twine upload --repository testpypi |
Sources: PUBLISHING.md:14-17, PUBLISHING.md:33-36
Pre-Publication Validation
Before a release is tagged, the framework requires comprehensive local validation using specialized scripts. The scripts/validate_pypi_ready.py script serves as the primary gatekeeper for package integrity. Sources: PUBLISHING.md:223-233
Validation Checks
The validation script performs several critical audits:
- Package Structure: Verifies the existence of mandatory files like
README.md,LICENSE, andpyproject.toml. - Version Consistency: Ensures the version string matches across
superclaude/__init__.py,setup.py,pyproject.toml, andCHANGELOG.md. - Dependency Audit: Validates runtime and development dependencies for compatibility and security.
- Entry Points: Verifies that the
SuperGeminiandsuperclaudeconsole scripts are correctly defined.
Sources: PUBLISHING.md:225-233, PUBLISHING.md:330-335
Build and Distribution
The build process generates two primary distribution formats: Source Distributions (sdist) and Wheels (bdist_wheel). Sources: PUBLISHING.md:435-465
This sequence diagram shows the transition from source code to the creation and uploading of distribution artifacts.
Sources: PUBLISHING.md:73-81, PUBLISHING.md:435-465
Distribution Contents
- Source Distribution (.tar.gz): Contains the full package source, including
setup.py,requirements.txt, and behavioral instructions inSuperGemini/. - Wheel Distribution (.whl): A compiled format containing the package code and metadata in the
dist-infodirectory for faster installation.
Sources: PUBLISHING.md:436-465
Version Management
SuperGemini adheres to Semantic Versioning (SemVer) (MAJOR.MINOR.PATCH) to communicate the nature of changes in each release. Sources: PUBLISHING.md:315-325
Version Increments
- MAJOR: Applied for breaking changes or significant architectural updates (e.g., v4.0.0 architecture).
- MINOR: Applied for new features, additional agents, or new MCP server integrations.
- PATCH: Applied for backward-compatible bug fixes, security patches, or documentation updates.
Sources: PUBLISHING.md:315-320, CONTRIBUTING.md:48-52
The Single Source of Truth
The version is primarily managed in a VERSION file located in the project root. This version propagates to pyproject.toml, setup.py, and the internal package metadata during the build process. Sources: CLAUDE.md:258-268
GitHub Actions Automation
Automation is triggered by the creation of a Git tag (e.g., v4.0.1). GitHub Actions handles the heavy lifting of multi-platform testing and publication. Sources: PUBLISHING.md:165-175
Release Workflow Stages
- Multi-Platform Testing: Runs the test suite on Python versions 3.8 through 3.12 across Linux, macOS, and Windows.
- Security Validation: Executes
safetyandbanditto scan for dependency vulnerabilities and code security issues. - Build: Generates the package distribution artifacts.
- Publish: Uploads the artifacts to PyPI using a scoped
PYPI_API_TOKEN. - GitHub Release: Creates a release entry on GitHub populated with changelog notes and the built assets.
Sources: PUBLISHING.md:188-198, PUBLISHING.md:213-218
Post-Publication Procedures
Once publication is complete, several verification steps are required to ensure the release is successfully deployed. Sources: PUBLISHING.md:610-630
- Registry Verification: Querying the PyPI JSON API to confirm the new version is live.
- Installation Test: Executing
pip install SuperGemini==<version>in a clean virtual environment to verify accessibility. - Entry Point Check: Running
SuperGemini --versionandSuperGemini install --list-componentsto confirm core functionality. - Community Notification: Updating GitHub Discussions and closing resolved issues related to the release.
Sources: PUBLISHING.md:612-625, PUBLISHING.md:640-645
Summary
The Build & Release process of the SuperGemini Framework is a comprehensive system designed to maintain professional standards of software delivery. By combining local validation scripts with automated CI/CD pipelines, the project ensures that every release on PyPI is tested for cross-platform compatibility and security. This systematic approach supports the project's mission of providing a stable and reliable meta-programming framework for the Gemini CLI ecosystem. Sources: PUBLISHING.md:3-12, CODE_OF_CONDUCT.md:12-16