Release Requirements

This document contains requirements for the syspilot release process.

Document Version: 0.1 Last Updated: 2026-01-30

Requirement: Semantic Versioning SYSPILOT_REQ_REL_SEMVER
status: implemented
tags: release, versioning
priority: mandatory
links outgoing: SYSPILOT_US_REL_CREATE
links incoming: INST_SYSPILOT_REQ_REL_VERSION_FILE, SYSPILOT_SPEC_DOC_RELEASE_NOTES_STRUCTURE, SYSPILOT_SPEC_REL_VERSION_FORMAT, SYSPILOT_SPEC_REL_WORKFLOW, SYSPILOT_REQ_WF_RELEASE_SEQUENCE

Description: syspilot SHALL use Semantic Versioning (MAJOR.MINOR.PATCH) for all releases.

Rationale: Semantic Versioning communicates compatibility and scope of changes clearly to users. GitHub Releases convention uses SemVer.

Acceptance Criteria:

  • AC-1: Version numbers follow MAJOR.MINOR.PATCH format

  • AC-2: MAJOR increments indicate breaking changes

  • AC-3: MINOR increments indicate new features (backward compatible)

  • AC-4: PATCH increments indicate bug fixes

  • AC-5: Pre-release versions use suffixes (-beta, -alpha, -rc.1)

  • AC-6: Version is stored in version.json
Requirement: GitHub Release Publication SYSPILOT_REQ_REL_GITHUB_PUBLISH
status: implemented
tags: release, distribution, github
priority: mandatory
links outgoing: SYSPILOT_US_REL_CREATE
links incoming: INST_SYSPILOT_REQ_REL_GITHUB_PUBLISH, SYSPILOT_SPEC_REL_GIT_TAG, SYSPILOT_SPEC_REL_WORKFLOW, SYSPILOT_SPEC_INST_RELEASE_STRUCTURE, SYSPILOT_REQ_INST_GITHUB_RELEASES, SYSPILOT_REQ_REL_GITHUB_ACTIONS, SYSPILOT_REQ_WF_RELEASE_SEQUENCE

Description: syspilot SHALL publish releases via GitHub Releases.

Rationale: GitHub Releases provides versioned distribution, release notes, and asset downloads in a standard platform.

Acceptance Criteria:

  • AC-1: Each release creates a Git tag with version number

  • AC-2: Release includes release notes describing changes

  • AC-3: GitHub automatically creates .zip and .tar.gz archives

  • AC-4: Users can view release history on GitHub

  • AC-5: Latest release is clearly marked
Requirement: Release Notes Generation SYSPILOT_REQ_REL_NOTES
status: approved
tags: release, documentation
priority: mandatory
links outgoing: SYSPILOT_US_REL_CREATE, SYSPILOT_REQ_DOC_RELEASE_NOTES
links incoming: INST_SYSPILOT_REQ_REL_NOTES_FORMAT, SYSPILOT_SPEC_REL_NOTES_STRUCTURE, SYSPILOT_SPEC_REL_AGENT, SYSPILOT_REQ_DOC_RELEASE_NOTES

Description: syspilot SHALL generate release notes for each version.

Rationale: Release notes communicate what changed to users and help them decide whether to update.

Acceptance Criteria:

  • AC-1: Release notes list new features

  • AC-2: Release notes list bug fixes

  • AC-3: Release notes list breaking changes

  • AC-4: Release notes reference User Stories/Requirements where applicable

  • AC-5: Release notes include migration guidance for breaking changes
Requirement: Pre-Release Validation SYSPILOT_REQ_REL_VALIDATION
status: implemented
tags: release, quality, validation
priority: mandatory
links outgoing: SYSPILOT_US_REL_VALIDATE
links incoming: SYSPILOT_SPEC_REL_VALIDATION_CHECKLIST, SYSPILOT_SPEC_REL_WORKFLOW, SYSPILOT_SPEC_INST_SELF_INSTALL, SYSPILOT_REQ_REL_GITHUB_ACTIONS, SYSPILOT_REQ_WF_RELEASE_SEQUENCE

Description: syspilot SHALL validate releases before publication.

Rationale: Pre-release validation prevents distributing broken releases and maintains user trust.

Acceptance Criteria:

  • AC-1: All validation checks must pass before release

  • AC-2: Validation failure blocks release publication

  • AC-3: Validation report shows which checks failed

  • AC-4: Maintainer can review validation results before approving
Requirement: Documentation Build Verification SYSPILOT_REQ_REL_DOC_BUILD
status: implemented
tags: release, validation, documentation
priority: mandatory
links outgoing: SYSPILOT_US_REL_VALIDATE, SYSPILOT_REQ_CORE_SPHINX_NEEDS
links incoming: SYSPILOT_SPEC_IMPL_QUALITY_GATES, SYSPILOT_SPEC_REL_VALIDATION_CHECKLIST, SYSPILOT_SPEC_REL_GITHUB_ACTIONS, SYSPILOT_SPEC_REL_GITHUB_PAGES, SYSPILOT_REQ_REL_GITHUB_ACTIONS

Description: syspilot SHALL verify documentation builds successfully before release.

Rationale: Broken documentation prevents users from understanding and using the system correctly.

Acceptance Criteria:

  • AC-1: Sphinx build completes without errors

  • AC-2: All sphinx-needs links are valid

  • AC-3: No orphaned requirements or design elements
Requirement: Agent Functionality Testing SYSPILOT_REQ_REL_AGENT_TEST
status: implemented
tags: release, validation, agents
priority: mandatory
links outgoing: SYSPILOT_US_REL_VALIDATE
links incoming: SYSPILOT_SPEC_REL_VALIDATION_CHECKLIST, SYSPILOT_SPEC_REL_GITHUB_ACTIONS, SYSPILOT_REQ_REL_GITHUB_ACTIONS

Description: syspilot SHALL verify agent functionality before release.

Rationale: Agents are the primary user interface for syspilot. Non-functional agents render the system unusable.

Acceptance Criteria:

  • AC-1: All agent definition files parse correctly

  • AC-2: Agent prompts contain no syntax errors

  • AC-3: Critical agent workflows are tested (setup, change, implement)

  • AC-4: Agent dependencies (scripts, templates) are verified
Requirement: GitHub Actions Automation SYSPILOT_REQ_REL_GITHUB_ACTIONS
status: implemented
tags: release, automation, ci-cd
priority: high
links outgoing: SYSPILOT_US_REL_CREATE, SYSPILOT_US_REL_VALIDATE, SYSPILOT_REQ_REL_VALIDATION, SYSPILOT_REQ_REL_DOC_BUILD, SYSPILOT_REQ_REL_AGENT_TEST, SYSPILOT_REQ_REL_GITHUB_PUBLISH
links incoming: INST_SYSPILOT_REQ_REL_CI_PIPELINE, SYSPILOT_SPEC_REL_GITHUB_ACTIONS

Description: syspilot SHOULD automate release validation and publication via GitHub Actions.

Rationale: Automation reduces human error, ensures consistency, and speeds up the release process.

Acceptance Criteria:

  • AC-1: GitHub Action validates releases on version tags

  • AC-2: GitHub Action builds documentation

  • AC-3: GitHub Action runs validation checks

  • AC-4: GitHub Action publishes to GitHub Releases on success

  • AC-5: GitHub Action publishes documentation to GitHub Pages

  • AC-6: GitHub Action can be triggered manually for testing
Requirement: Release Agent KISS Template SYSPILOT_REQ_REL_PROCESS_DOC
status: implemented
tags: release, agent, template
priority: medium
links outgoing: SYSPILOT_US_REL_AGENT_TEMPLATE
links incoming: INST_SYSPILOT_REQ_REL_CHANGE_ARCHIVE, SYSPILOT_SPEC_REL_AGENT

Description: syspilot SHALL provide a release agent template that is short, generic, and focuses on project-specific design decisions rather than prescribing every release step.

Rationale: LLMs know how to perform standard release tasks (version bump, tagging, release notes). The agent only needs to document project-specific decisions to guide the LLM.

Acceptance Criteria:

  • AC-1: Release agent template contains a “Release Decisions” section for project-specific configuration

  • AC-2: Decisions are stored in the agent file itself (no separate config file)

  • AC-3: On first invocation without existing decisions, the agent bootstraps by asking the user

  • AC-4: Agent does not prescribe individual release steps (LLM handles standard release flow)

  • AC-5: Template is usable for any project, not syspilot-specific

Traceability

All traceability is automatically generated by Sphinx-Needs.

ID

Title

Status

Tags

SYSPILOT_REQ_REL_AGENT_TEST

Agent Functionality Testing

implemented

release; validation; agents

SYSPILOT_REQ_REL_DOC_BUILD

Documentation Build Verification

implemented

release; validation; documentation

SYSPILOT_REQ_REL_GITHUB_ACTIONS

GitHub Actions Automation

implemented

release; automation; ci-cd

SYSPILOT_REQ_REL_GITHUB_PUBLISH

GitHub Release Publication

implemented

release; distribution; github

SYSPILOT_REQ_REL_NOTES

Release Notes Generation

approved

release; documentation

SYSPILOT_REQ_REL_PROCESS_DOC

Release Agent KISS Template

implemented

release; agent; template

SYSPILOT_REQ_REL_SEMVER

Semantic Versioning

implemented

release; versioning

SYSPILOT_REQ_REL_VALIDATION

Pre-Release Validation

implemented

release; quality; validation