Skip to content

cicd.md

Latest commit

 

History

History
303 lines (200 loc) · 8.99 KB

cicd.md

File metadata and controls

303 lines (200 loc) · 8.99 KB

CI/CD Pipeline Documentation

Comprehensive guide to SuperDoc's continuous integration and deployment workflows. For contribution guidelines, see CONTRIBUTING.md.

Overview

SuperDoc implements a streamlined dual-track release strategy with fully automated versioning:

  • @next channel: Pre-release versions from main while we build toward v1
  • @latest channel: Stable versions from stable branch
  • @X.x channels: Patch releases for maintenance branches

All releases are automated through semantic-release based on conventional commits.

Workflow Architecture

main (next) → stable (latest) → X.x (maintenance)
     ↓             ↓                ↓
  pre-releases  stable releases  patch releases

Branch Strategy

  • main: Development branch, releases to @next
  • stable: Production branch, releases to @latest
  • X.x: Maintenance branches for patching old versions

GitHub Actions Workflows

Core Workflows

1. PR Validation (pr-validation.yml)

Triggers: All pull requests

Checks:

  • Conventional commit validation
  • Code formatting (Prettier)
  • Linting (ESLint)
  • Unit tests
  • Visual regression tests
  • E2E tests (main branch only)

Required to pass before merge.

2. Release (release.yml)

Triggers:

  • Push to main, stable, or *.x branches
  • Manual workflow dispatch

Process:

  1. Run full test suite
  2. Build packages
  3. Semantic-release publishes:
    • From main: X.Y.Z-next.N to @next
    • From stable: X.Y.Z to @latest
    • From X.x: X.x.Y to @X.x

Post-release:

  • Stable releases auto-sync to main
  • Version bump commit added to main

3. Promote to Stable (promote-stable.yml)

Trigger: Manual workflow dispatch or scheduled runs at 05:00 UTC on Tuesdays and Saturdays

Input: Optional candidate branch name (defaults to merge/main-into-stable-YYYY-MM-DD)

Actions:

  • Creates a fresh candidate branch from stable
  • Merges main into that branch
  • Opens a PR targeting stable
  • If the merge conflicts, commits the conflicted merge to the branch so a human can resolve it there
  • Merging that PR triggers the automatic stable release workflow

4. Release Qualification Dispatch (release-qualification-dispatch.yml)

Trigger: Pull requests targeting stable (opened, reopened, synchronize, ready_for_review)

Actions:

  • Sends the PR head SHA and branch metadata to the Labs release-orchestrator service
  • Polls Labs for the terminal release-qualification state
  • Uses the GitHub Actions job itself as the required public status check
  • Re-triggers automatically when new commits are pushed to the PR branch

Only same-repository PRs dispatch to Labs. Forked PRs are intentionally skipped so private Labs credentials are never exposed to untrusted branches.

Required configuration:

  • variable: LABS_RELEASE_QUALIFICATION_URL
  • secret: LABS_RELEASE_QUALIFICATION_TOKEN

5. Create Patch Branch (create-patch.yml)

Trigger: Manual workflow dispatch

Input: Major.minor version (e.g., 1.2)

Actions:

  • Creates X.x branch from last stable tag
  • Enables patching of old versions

6. Forward Port (forward-port.yml)

Triggers:

  • New version tags on maintenance branches
  • Manual workflow dispatch

Actions:

  • Cherry-picks fixes from maintenance branches to main
  • Creates PR for review
  • Labels with forward-port

Support Workflows

7. Test Suite (test-suite.yml)

Type: Reusable workflow

Components:

  • Code quality checks (format, lint)
  • Unit tests (Vitest)
  • Visual regression tests (Playwright)
  • E2E tests (external service)

8. Visual Tests (test-example-apps.yml)

Triggers:

  • Changes to examples/** or packages/**/src/**
  • Manual dispatch for screenshot updates

Release Strategy

Version Progression

main (1.0.0-next.1) → merge to stable → 1.0.0 (@latest)
         ↓                                    ↓
    1.1.0-next.1                         (if needed)
         ↓                               create 1.0.x
    continues...                         → 1.0.1, 1.0.2...

Semantic Versioning

Version bumps are automatic based on commit messages:

Commit Prefix Version Change Example Result
fix: Patch fix: resolve memory leak 1.2.3 → 1.2.4
feat: Minor feat: add PDF export 1.2.3 → 1.3.0
feat!: or BREAKING CHANGE: Major feat!: new API format 1.2.3 → 2.0.0
chore:, docs:, style: None docs: update README No change

NPM Distribution Tags

  • @next: Latest pre-release from main
    • Install: npm install superdoc@next
    • Format: X.Y.Z-next.N
  • @latest: Current stable release
    • Install: npm install superdoc
    • Format: X.Y.Z
  • @X.x: Maintenance releases
    • Install: npm install superdoc@1.2.x
    • Format: X.x.Y

ℹ️ The legacy scoped package @harbour-enterprises/superdoc is mirrored with the same version and dist-tag for every release channel above.

CLI Release

The CLI (apps/cli) has its own semantic-release pipeline with tag format cli-v${version}.

Automated (CI)

Trigger Channel Tag example
Push to main @next cli-v0.3.0-next.1
Push to stable @latest cli-v0.3.0

The workflow is .github/workflows/release-cli.yml. It analyzes commits across multiple packages (see apps/cli/.releaserc.cjs for the includePaths list).

Local Release

Command What it does
pnpm run release:local Releases superdoc → CLI → SDK in sequence on stable
pnpm run release:local:superdoc Releases superdoc only
pnpm run release:local:cli Releases CLI only
pnpm run release:local:sdk Releases SDK only

All accept -- --dry-run to preview without publishing. The combined orchestrator (release:local) enforces a stable branch guard (override with --branch=<name>).

@semantic-release/git automatically pushes version commits and tags when releasing on the stable branch. This is existing behavior for superdoc, CLI, and SDK.

SDK stable releases publish both npm (via sdk-release-publish.mjs) and PyPI (via twine). Prerequisites: pip install twine and PYPI_PUBLISH_TOKEN in your shell env.

Raw Platform Publish (bypass semantic-release)

Command What it does
pnpm run cli:publish:raw Builds and publishes platform binaries directly
pnpm run cli:publish:raw:dry Dry-run of the above

These skip semantic-release entirely — useful for re-publishing a failed platform upload.

Workflow Scenarios

Scenario 1: Feature Development

  1. Create feature branch from main
  2. Open PR → triggers validation
  3. Merge to main → releases 1.1.0-beta.1

Scenario 2: Creating Stable Release

  1. Run "Promote to Stable" workflow
  2. Review the generated PR from the candidate branch into stable
  3. Labs receives the PR head SHA, records the qualification run, and the workflow job polls Labs for the terminal result
  4. If needed, resolve merge conflicts on the candidate branch and push fixes
  5. Re-run or wait for qualification on the new PR head SHA
  6. Merge the PR into stable
  7. Automatically publishes 1.1.0 as @latest
  8. Syncs back to main with version bump

Scenario 3: Hotfix to Current Stable

  1. Create fix branch from stable
  2. Commit: fix: resolve critical bug
  3. Merge PR → releases 1.1.1
  4. Auto-syncs to main

Scenario 4: Patch Old Version

  1. Run "Create Patch Branch" for version 1.0
  2. Creates 1.0.x branch
  3. Apply fix → releases 1.0.1
  4. Forward-port creates PR to main

Branch Protection Rules

Main Branch

  • Require pull request before merging
  • Require status checks to pass
  • Require branches to be up to date
  • No force pushes

Stable Branch

  • Same as main
  • Allow direct merge from main for promotion

Maintenance Branches (*.x)

  • Require pull request
  • Allow maintainer fixes
  • No force pushes

Monitoring & Debugging

Check Release Status

# View latest releases
pnpm view superdoc versions --json

# Check current tags
pnpm view superdoc dist-tags

# Dry run to preview release
pnpx semantic-release --dry-run --no-ci

Common Issues

Version not incrementing on main:

  • After stable release, main needs a feat/fix commit to bump version
  • Automatic version bump commit handles this

Maintenance branch conflicts:

  • Only create X.x branches AFTER moving past that version on stable
  • Example: Create 1.0.x only after stable is at 1.1.0+

For contribution guidelines and development setup, see CONTRIBUTING.md.
For questions about CI/CD, reach out on Discord or GitHub Discussions.