Skip to content

open-source-release-checklist.md

Latest commit

 

History

History
158 lines (126 loc) · 7.93 KB

open-source-release-checklist.md

File metadata and controls

158 lines (126 loc) · 7.93 KB
Raw

Open Source Release Checklist

Status date: 2026-02-18 Scope: repository-level launch readiness for Recurgent (Ruby runtime first, Lua runtime scaffolded)

1. Product Positioning and Scope

  • README narrative is explicit on project intent (LLM-native Tool Builder/Tool delegation runtime).
  • Runtime scope is clear: Ruby is production path, Lua is planned parity path.
  • Non-goals are explicit (for example: no hard runtime validation of delegation contracts in current phase).
  • Naming language is consistent across docs (Tool Builder, Tool, Delegate, Outcome, Delegation Budget).

2. Legal and Policy Baseline

  • LICENSE present and correct.
  • CODE_OF_CONDUCT.md present.
  • CONTRIBUTING.md present.
  • SECURITY.md present.
  • SUPPORT.md present.
  • Verify copyright and year are correct everywhere.
  • Confirm all example snippets are safe to distribute publicly (no proprietary content/API secrets).
  • Confirm repository has no trademark-sensitive or third-party restricted assets.

3. Repository Hygiene

  • Remove accidental local/dev artifacts (scratch files, tmp outputs, local state dumps).
  • Ensure .gitignore excludes local logs, tokens, generated binaries, and editor artifacts.
  • Confirm no secrets in history and working tree (gitleaks clean).
  • Ensure no sensitive issue data is left in local tracker exports intended for publish.
  • Validate top-level structure is intentional (README.md, docs/, runtimes/, specs/, bin/).

4. Documentation Readiness

  • README.md has:
    • clear value proposition
    • quickstart that works
    • minimal runnable example
    • links to docs index and FAQs
  • docs/index.md links are complete and not stale.
  • docs/onboarding.md setup steps are reproducible with mise.
  • docs/product-specs/delegation-contracts.md matches runtime behavior (symmetry for Agent.for and delegate).
  • docs/observability.md matches emitted JSONL fields (trace_id, call_id, contract_source, etc.).
  • docs/delegate-vs-for.md examples reflect current API.
  • ADR index includes all active design decisions and no stale statuses.
  • Add/verify a concise “Known limitations” section:
    • stdlib-only execution constraints
    • provider may return invalid payloads
    • tolerant outcomes may need caller-side quality checks

5. API and Runtime Contract Stability

  • Agent.for(...) and delegate(...) contract interfaces are symmetric and documented.
  • Error taxonomy is documented and stable (provider, invalid_code, execution, timeout, budget_exceeded).
  • Capability-boundary prompt rule is present in runtime prompts.
  • Logging path normalizes UTF-8 and avoids JSON 3.0 breakage warnings.
  • Conformance docs in specs/contract/v1/ reflect current behavior.

6. Quality Gates (Ruby Runtime)

  • mise exec -- bundle exec rspec passes in runtimes/ruby.
  • mise exec -- bundle exec rubocop passes in runtimes/ruby.
  • Class-1 simulation readiness CI (G0-G5) passes for current release commit (.github/workflows/simulation-readiness-ci.yml).
  • Deterministic examples run successfully (especially observability_demo.rb).
  • At least one manual smoke run validates tolerant failure handling for provider-invalid payload.
  • Regression coverage exists for:
    • contract merge semantics
    • prompt capability-boundary rules
    • logging metadata (contract_source, trace fields)
    • encoding normalization in logs

7. CI, Security, and Dependency Automation

  • CI workflow present for tests/lint.
  • Security workflow present (dependency review, bundler audit, secret scanning).
  • Dependabot config present.
  • CI required checks are enforced via branch protection.
  • Security scanning alerts are empty or triaged.
  • Dependency update policy is documented and operational.

8. Community Workflow and Anti-Spam Controls

  • Issue templates present.
  • PR template present.
  • CODEOWNERS present.
  • PR compliance workflow present.
  • Stale workflow present.
  • Maintainer triage playbook includes bot/low-value PR handling criteria.
  • PR compliance messaging clearly references CONTRIBUTING.md and CODE_OF_CONDUCT.md.
  • Labels are configured in repo (ready-for-pr, accepted, good first issue, help wanted).

9. GitHub Repository Settings (Manual)

  • Branch protection on main:
    • require PR reviews
    • require status checks (CI, PR Compliance, Security)
    • dismiss stale approvals on new commits
    • block force pushes and deletions
  • Enable private vulnerability reporting.
  • Set repository description and topics.
  • Enable Discussions (optional, but recommended for usage questions).
  • Configure default issue/PR labels and triage permissions.

10. Release Artifact and Versioning

  • Decide and tag first public version (for example v0.1.0).
  • Ensure CHANGELOG.md has release notes for initial public release.
  • Ensure runtime gem metadata links are valid (homepage, source_code_uri, changelog_uri).
  • Confirm release process doc aligns with actual tagging and publishing commands.
  • Prepare release notes with:
    • what is stable
    • what is experimental
    • migration notes (if any)

11. Launch Day Checklist

  • Run final clean-room setup using onboarding docs.
  • Run full tests/lint one final time on clean tree.
  • Verify examples used in README run without manual patching.
  • Publish release/tag.
  • Announce with clear expectations and known limitations.
  • Monitor first 24h issues and discussions.

12. Post-Launch (First 2 Weeks)

  • Triage incoming issues daily.
  • Classify bug reports into contract/runtime/docs buckets.
  • Tighten docs where user confusion is repeated.
  • Track top failure modes from logs and convert to tests/docs.
  • Create next milestone focused on highest-leverage reliability fixes.

13. Future Work Backlog

  • Add generated-code caching layer (cache generated code for repeated role/method/input patterns).
  • Add persistent generated-code layer (store/reuse generated code across sessions to grow software agentically).

Local Verification Notes

Completed locally on 2026-02-18:

  • Runtime checks:
    • cd runtimes/ruby && bundle exec rspec (238 examples, 0 failures)
    • cd runtimes/ruby && bundle exec rubocop (clean)
    • cd runtimes/ruby && mise exec -- ruby examples/observability_demo.rb (tolerant failure behavior validated)
  • Documentation/link checks:
    • docs/index.md file references resolved locally (no missing file paths)
  • Hygiene:
  • Security automation notes:
    • GitHub Dependabot vulnerability alerts enabled for the repository.
    • Branch protection enforces required checks: Ruby test and lint, Enforce PR template and issue-first policy, bundler-audit, gitleaks.
    • Secret scanning and code scanning still require repository visibility/licensing changes (tracked in Section 9 and Section 7).
    • v0.1.0 tag and release published: https://github.com/kulesh/recurgent/releases/tag/v0.1.0.

Suggested Operating Rule

Use this checklist as a gate: launch when sections 1–8 are complete and section 9 has no open critical settings.