Skip to content

RELEASING.md

Latest commit

 

History

History
180 lines (120 loc) · 4.17 KB

RELEASING.md

File metadata and controls

180 lines (120 loc) · 4.17 KB

Release Process

Prerequisites

  • Write access to the repository
  • Ability to trigger GitHub Actions workflows
  • Access to publish to crates.io

Release Workflow

pctx uses cargo-dist for automated releases. The workflow is triggered manually via GitHub Actions workflow dispatch.

Step-by-Step Process

1. Prepare the Release

Update the version number in the package manifest:

# Edit crates/pctx/Cargo.toml and update the version field
# Example: version = "0.2.0"

2. Update the Changelog

Edit CHANGELOG.md following Keep a Changelog format:

## [0.2.0] - 2025-11-10

### Added
- New feature description

### Changed
- Changed feature description

### Fixed
- Bug fix description

Update the comparison links at the bottom:

[0.2.0]: https://github.com/portofcontext/pctx/compare/v0.1.0...v0.2.0

3. Commit and Push Changes

git add crates/pctx/Cargo.toml CHANGELOG.md Cargo.lock
git commit -m "chore: prepare release v0.2.0"
git push origin main

4. Trigger the Release

  1. Go to GitHub Actions
  2. Click "Run workflow"
  3. Enter the tag name (e.g., v0.2.0)
  4. Click "Run workflow"

The workflow will:

  • Build binaries for all supported platforms (Linux, macOS, Windows)
  • Create installers (shell, Homebrew, npm)
  • Generate checksums and attestations for supply chain security
  • Create a GitHub Release with all artifacts
  • Publish Homebrew formula to the tap repository

5. Verify the Release

Once the workflow completes (~15-20 minutes):

  1. Check the Releases page
  2. Verify all platform binaries are present
  3. Test the installation methods:
# Shell installer (Linux/macOS)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/portofcontext/pctx/releases/latest/download/pctx-installer.sh | sh

# Homebrew (macOS/Linux)
brew install portofcontext/tap/pctx

# npm (all platforms)
npm install -g @portofcontext/pctx

6. Publish to crates.io (Optional)

To publish Rust library crates to crates.io:

make publish-crates

This runs locally using cargo-smart-release to handle multi-crate dependencies.

Release Types

Stable Releases

Version format: v1.0.0, v1.2.3

  • Fully tested and production-ready
  • Published to all distribution channels
  • Creates a standard GitHub Release

Pre-releases

Version format: v1.0.0-alpha.1, v1.0.0-beta.2, v1.0.0-rc.1

  • For testing and early access
  • Marked as "pre-release" on GitHub
  • May not be published to all channels

Distribution Channels

GitHub Releases

All releases are published to GitHub Releases with:

  • Pre-built binaries for all platforms
  • Source archives
  • SHA256 checksums
  • GitHub Attestations for supply chain security
  • Auto-generated release notes from CHANGELOG.md

Installers

Shell Script (Linux/macOS)

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/portofcontext/pctx/releases/latest/download/pctx-installer.sh | sh

Features:

  • Detects platform automatically
  • Verifies checksums
  • Installs to ~/.local/bin

Homebrew (macOS/Linux)

brew tap portofcontext/tap
brew install pctx

Auto-updated when releases are published.

npm (all platforms)

npm install -g @portofcontext/pctx

Provides pre-built native binaries for Node.js users.

Platform Support

pctx is built for the following platforms:

  • Linux: x86_64 (glibc and musl), aarch64 (glibc and musl)
  • macOS: x86_64 (Intel), aarch64 (Apple Silicon)
  • Windows: x86_64 (MSVC)

Best Practices

  1. Always update CHANGELOG.md before releasing
  2. Test locally with dist plan and dist build
  3. Use semantic versioning (MAJOR.MINOR.PATCH)
  4. Tag after merging to main to ensure clean builds
  5. Monitor the release workflow to catch issues early

Getting Help