Technical Design: phase-3-post-release-polish

Technical Design: phase-3-post-release-polish

Metadata

• Feature: phase-3-post-release-polish
• Status: DRAFT
• Created: 2026-02-07
• Author: Factory Design Mode
• Issue: #191

1. Overview

1.1 Summary

Four independent infrastructure/CI improvements for post-v0.2.0 polish: GitHub Sponsors setup, release notes automation config, documentation link checking in CI, and expanded pre-commit hooks. All tasks are file-creation or file-modification with zero interdependencies — fully parallelizable.

1.2 Goals

• Enable GitHub Sponsors button on the repository
• Auto-categorize release notes by PR labels
• Catch broken documentation links before merge
• Enforce whitespace/format hygiene via pre-commit

1.3 Non-Goals

• Terminal demo recording (manual)
• Social preview image (manual)
• Docker Hub publishing (deferred)
• Changing existing CI required checks

2. Architecture

2.1 High-Level Design

No new code components. All changes are configuration files.

┌──────────────────────────────────────────────────────┐
│                  GitHub Repository                    │
│                                                       │
│  .github/                                             │
│  ├── FUNDING.yml        ← NEW (Sponsors button)       │
│  ├── release.yml        ← NEW (release note categories)│
│  └── workflows/                                       │
│      └── ci.yml         ← MODIFY (add lychee job)     │
│                                                       │
│  .pre-commit-config.yaml ← MODIFY (add standard hooks)│
│                                                       │
│  CHANGELOG.md           ← MODIFY (add entries)        │
└──────────────────────────────────────────────────────┘

2.2 Component Breakdown

2.3 Data Flow

No runtime data flow — all components are static config consumed by GitHub or git hooks at build/commit time.

3. Detailed Design

3.1 FUNDING.yml

# .github/FUNDING.yml
github: rocklambros
# buy_me_a_coffee:
# open_collective:

3.2 Release Notes Config

# .github/release.yml
changelog:
  exclude:
    labels:
      - skip-changelog
      - duplicate
  categories:
    - title: New Features
      labels:
        - enhancement
    - title: Bug Fixes
      labels:
        - bug
    - title: Documentation
      labels:
        - documentation
    - title: Dependencies
      labels:
        - dependencies
    - title: Other Changes
      labels:
        - "*"

3.3 Link Checker CI Job

New job link-check added to .github/workflows/ci.yml. Runs in parallel with quality (no dependency). Uses lychee-action with:

• Scope: docs/**/*.md README.md CONTRIBUTING.md CHANGELOG.md
• Excludes: localhost, example.com, PyPI badge URLs
• Retries: 3, timeout: 30s
• continue-on-error: true (non-blocking warning)

3.4 Pre-commit Expansion

Add pre-commit/pre-commit-hooks repo block after existing ruff block:

• trailing-whitespace
• end-of-file-fixer
• check-yaml
• check-json
• check-toml
• check-added-large-files (args: ['--maxkb=500'])

4. Key Decisions

4.1 Link Checker: Non-Blocking

Context: External URLs can be flaky (rate limits, timeouts), causing false CI failures.

Options Considered:

1. Blocking (required): strict but risks flaky failures
2. Non-blocking (continue-on-error): catches issues as warnings, no false failures
3. Separate workflow: more complex, harder to discover

Decision: Non-blocking via continue-on-error: true

Rationale: Requirements explicitly say "warning (non-blocking) initially". Can promote later.

Consequences: Broken links won't block PRs but will be visible in CI output.

4.2 Lychee Action vs CLI

Context: Need a link checker in CI.

Options Considered:

1. lychee-action GitHub Action: turnkey, maintained, cached
2. Raw lychee CLI install: more control, more setup
3. markdown-link-check: older, slower, npm-based

Decision: lychee/lychee-action GitHub Action

Rationale: Most maintained, fastest, Rust-based, first-class GitHub Action support.

Consequences: Depends on external action. Pin to specific version for reproducibility.

5. Implementation Plan

5.1 Phase Summary

All implementation tasks are independent — max parallelization at Level 1.

5.2 File Ownership

5.3 Dependency Graph

graph TD
    T001[TASK-001: FUNDING.yml] --> T005[TASK-005: CHANGELOG]
    T002[TASK-002: release.yml] --> T005
    T003[TASK-003: Link checker] --> T005
    T004[TASK-004: Pre-commit] --> T005

6. Risk Assessment

7. Testing Strategy

7.1 Verification Commands

• TASK-001: test -f .github/FUNDING.yml && grep -q 'github: rocklambros' .github/FUNDING.yml
• TASK-002: test -f .github/release.yml && python -c "import yaml; d=yaml.safe_load(open('.github/release.yml')); assert len(d['changelog']['categories']) == 5"
• TASK-003: python -c "import yaml; ci=yaml.safe_load(open('.github/workflows/ci.yml')); assert 'link-check' in ci['jobs']"
• TASK-004: grep -c 'id:' .pre-commit-config.yaml | grep -q '8'
• TASK-005: grep -q 'FUNDING.yml' CHANGELOG.md && grep -q 'release.yml' CHANGELOG.md && grep -q 'lychee' CHANGELOG.md && grep -q 'pre-commit' CHANGELOG.md

8. Parallel Execution Notes

8.1 Safe Parallelization

• Level 1: 4 tasks, zero shared files, fully parallel
• Level 2: 1 task (CHANGELOG), depends on all L1 tasks

8.2 Recommended Workers

• Minimum: 1 worker (sequential)
• Optimal: 4 workers (one per L1 task)
• Maximum: 4 workers (no benefit beyond)

8.3 Estimated Duration

• Single worker: ~15 min
• With 4 workers: ~10 min (L1 parallel + L2 sequential)
• Speedup: ~1.5x

9. Approval