Release Process

Relevant source files

The following files were used as context for generating this wiki page:

• dev/publish-release.sh
• CHANGELOG.md
• Development.md
• bindings/rust/Cargo.toml
• package.json
• cmd/scip/main.go

The SCIP release process ensures that new versions of the protocol, CLI, and language bindings are published consistently across the ecosystem. It involves manual preparation of metadata, automated validation via shell scripts, and automated artifact generation through GitHub Actions.

The process is designed to synchronize version numbers across multiple language bindings (Go, Rust, TypeScript, Haskell) and the core CLI tool. This synchronization is critical because SCIP acts as a transmission format where producers and consumers must agree on the schema and protocol version.

Sources: Development.md:118-132, DESIGN.md:27-35

Release Preparation

Before a release can be triggered, several files must be updated manually to reflect the new version. This ensures that the documentation and the compiled binaries report the correct version information.

Version Synchronization Requirements

The following files must be updated with the new version string (formatted as M.N.P):

File Path	Purpose
CHANGELOG.md	Contains release notes for the new version.
cmd/scip/version.txt	Used by the Go CLI to report its version.
bindings/rust/Cargo.toml	Defines the version for the Rust crate.
bindings/rust/Cargo.lock	Updated lockfile for Rust dependencies.
docs/CLI.md	Updated documentation for the command-line interface.

Sources: Development.md:119-122, dev/publish-release.sh:14-25

Implementation Detail: Version Embedding

In the Go implementation, the version is embedded directly into the binary using Go's embed directive, reading from version.txt.

//go:embed version.txt
var version string

func scipApp() *cli.App {
    app := &cli.App{
        Name:    "scip",
        Version: fmt.Sprintf("v%s%s", strings.TrimSpace(version), gitSuffix()),
        // ...
    }
}

Sources: cmd/scip/main.go:34-51

Automation with publish-release.sh

The project uses a dedicated shell script, dev/publish-release.sh, to validate the environment and initiate the release by pushing a git tag.

Pre-flight Checks

The script performs several critical safety checks before proceeding:

1. Version Variable: Ensures the NEW_VERSION environment variable is set.
2. Changelog Verification: Checks if CHANGELOG.md contains an entry for the new version.
3. Metadata Consistency: Verifies that the version in cmd/scip/version.txt and bindings/rust/Cargo.toml matches NEW_VERSION.
4. Git State: Aborts if there are unstaged or uncommitted changes.
5. Branch Protection: Ensures the release is being published from the main branch.

Sources: dev/publish-release.sh:5-48

Execution Flow

The following diagram illustrates the logic executed by the release script:

The script uses the GitHub CLI (gh) to create the final release notes and attach instructions for downloading the platform-specific binaries.

Sources: dev/publish-release.sh:50-71

Automated Artifact Generation

Once the git tag is pushed to the repository, a GitHub Actions workflow (release.yml) is triggered automatically.

Artifacts and Distribution

• CLI Binaries: Built for multiple platforms and uploaded to the GitHub Release.
• Language Bindings: While some bindings are hand-written, others (TypeScript, Rust, Haskell) are auto-generated from the scip.proto schema.
• Release Notes: The script automatically generates a release description including a curl command for users to download the CLI.

Sources: Development.md:129-132, dev/publish-release.sh:58-69

Release Command Example

To trigger a release for version 0.6.1, a developer runs:

NEW_VERSION="0.6.1" ./dev/publish-release.sh

Sources: Development.md:127

Conclusion

The SCIP release process combines manual documentation updates with strict script-based validation to ensure version consistency across various language ecosystems. By enforcing checks on the main branch and verifying metadata in Go and Rust configurations before tagging, the project maintains a reliable distribution pipeline for its cross-language protocol.

Sources: Development.md:118-132, dev/publish-release.sh:5-48