Release¶
Release creation, validation, and automation.
Last Updated: 2026-02-15
Level 0: Stakeholder Needs (WHY)¶
As a ubFlow maintainer, I want to create official releases with version numbers, so that users can install stable, tested versions of ubFlow. Acceptance Scenarios:
|
As a ubFlow maintainer, I want to validate release quality before distribution, so that users receive stable, working releases. Acceptance Scenarios:
|
As a ubFlow user, I want to see how a release agent could work, so that I can create my own release automation for my projects. Acceptance Scenarios:
|
Level 1: Requirements (WHAT)¶
Release Requirements¶
This document contains requirements for the ubFlow release process.
Document Version: 0.1 Last Updated: 2026-01-30
Description: ubFlow 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:
|
Description: ubFlow SHALL publish releases via GitHub Releases. Rationale: GitHub Releases provides versioned distribution, release notes, and asset downloads in a standard platform. Acceptance Criteria:
|
Description: ubFlow SHALL generate release notes for each version. Rationale: Release notes communicate what changed to users and help them decide whether to update. Acceptance Criteria:
|
Description: ubFlow SHALL validate releases before publication. Rationale: Pre-release validation prevents distributing broken releases and maintains user trust. Acceptance Criteria:
|
Description: ubFlow SHALL verify documentation builds successfully before release. Rationale: Broken documentation prevents users from understanding and using the system correctly. Acceptance Criteria:
|
Description: ubFlow SHALL verify agent functionality before release. Rationale: Agents are the primary user interface for ubFlow. Non-functional agents render the system unusable. Acceptance Criteria:
|
Description: ubFlow SHOULD automate release validation and publication via GitHub Actions. Rationale: Automation reduces human error, ensures consistency, and speeds up the release process. Acceptance Criteria:
|
Description: ubFlow SHALL document the release process as a template for users. Rationale: Documenting ubFlow’s own release process provides a working example that users can adapt for their projects. Acceptance Criteria:
|
Level 2: Design (HOW)¶
Release Design Specifications¶
This document contains design specifications for the ubFlow release process.
Document Version: 0.1 Last Updated: 2026-01-30
Design: ubFlow uses Semantic Versioning with structure stored in version.json. Version Format:
version.json Structure: {
"version": "0.2.0",
"installedAt": "2026-01-30",
"ubFlowPath": "C:\\workspace\\ubFlow",
"docsType": "sphinx"
}
Version Bump Rules:
Examples:
|
Design: Releases are created via annotated Git tags that trigger GitHub Releases. Tag Naming Convention:
Tag Creation Process: # 1. Update version.json with new version
# 2. Commit version.json change
git add version.json
git commit -m "chore: bump version to 0.2.0"
# 3. Create annotated tag
git tag -a v0.2.0 -m "Release v0.2.0: Description"
# 4. Push tag (triggers GitHub Actions if configured)
git push origin v0.2.0
Tag Content:
Validation:
|
Design: Release notes follow structured markdown format with traceability. Release Notes File:
Release Notes Template: # ubFlow Release Notes
## v0.2.0 - 2026-01-30
### Summary
[One paragraph describing the release, generated from Change Documents]
### ⚠️ Breaking Changes
- [List breaking changes with migration guidance]
- References: NEED_XXX, REQ_YYY
### ✨ New Features
- [Feature description] (NEED_XXX, REQ_YYY)
- [Feature description] (NEED_XXX, REQ_YYY)
### 🐛 Bug Fixes
- [Fix description] (REQ_YYY)
- [Fix description] (REQ_YYY)
### 📚 Documentation
- [Doc updates]
### 🔧 Internal Changes
- [Refactoring, cleanup]
---
## v0.1.0 - 2026-01-15
...
Generation Process:
Traceability:
|
Design: Pre-release validation ensures release quality through manual checklist. Validation Checklist: Documentation:
Agents:
Scripts:
Git:
Validation Execution:
Manual Fallback Process: If GitHub Actions fails or is unavailable:
|
Design: GitHub Actions automate validation, documentation build, and release publication. Workflow File: Workflow Trigger:
Workflow Steps:
Environment Variables:
Failure Handling:
|
Design: Documentation is automatically published to GitHub Pages on release. GitHub Pages Configuration:
Build Process: # Install dependencies
pip install -r docs/requirements.txt
# Build Sphinx documentation
cd docs
sphinx-build -b html . _build/html
# Deploy to gh-pages branch
# (handled by GitHub Actions peaceiris/actions-gh-pages)
Dependencies: From
URL Structure:
Update Frequency:
Initial Setup (one-time):
|
Design: Release agent guides maintainer through release process interactively. Agent Definition: Agent Responsibilities:
Interaction Model: User: @ubFlow.release prepare v0.2.0
Agent: I found 3 merged Change Documents:
- install-update.md
- release-process.md
- agent-improvements.md
Based on these changes, I recommend a MINOR release (0.1.0 → 0.2.0).
Shall I generate release notes?
User: Yes
Agent: [Generates release note entry]
Preview:
## v0.2.0 - 2026-01-30
### Summary
This release adds the installation/update workflow...
### New Features
- Install/update mechanism (NEED_INST_NEW_PROJECT through NEED_INST_UPDATE)
- Release process documentation (NEED_REL_CREATE through NEED_REL_AGENT_TEMPLATE)
Approve and commit?
Implementation Options:
Template for Users: The release agent serves as a working example that users can adapt for their own projects, demonstrating:
|
Release Workflow¶
Design: The release workflow bundles multiple merged changes into a versioned release. Release Flow: Merged Changes (on main)
│
▼
┌─────────────────┐
│ 1. Version │ ──→ Update version.json, determine SemVer bump
└─────────────────┘
│
▼
┌─────────────────┐
│ 2. Validate │ ──→ sphinx-build, agent tests, quality checks
└─────────────────┘
│
▼ (all pass)
┌─────────────────┐
│ 3. Publish │ ──→ Git tag, GitHub Release, GitHub Pages
└─────────────────┘
│
▼
┌─────────────────┐
│ change / end │ (user decides)
└─────────────────┘
Scope: Unlike the change workflow (operates on one change), the release workflow operates across all changes since the last release. Automation: GitHub Actions automates steps 2 and 3 (see SPEC_REL_GITHUB_ACTIONS). Step 1 (version determination) requires maintainer judgment. |
Traceability¶
Stakeholder Needs¶
ID |
Title |
Status |
Priority |
|---|---|---|---|
Release Agent Template |
implemented |
medium |
|
Create ubFlow Release |
implemented |
mandatory |
|
Validate Release Quality |
implemented |
mandatory |
Requirements¶
ID |
Title |
Status |
Tags |
|---|---|---|---|
Agent Functionality Testing |
implemented |
release; validation; agents |
|
Documentation Build Verification |
implemented |
release; validation; documentation |
|
GitHub Actions Automation |
implemented |
release; automation; ci-cd |
|
GitHub Release Publication |
implemented |
release; distribution; github |
|
Release Notes Generation |
approved |
release; documentation |
|
Release Process Documentation |
implemented |
release; documentation; template |
|
Semantic Versioning |
implemented |
release; versioning |
|
Pre-Release Validation |
implemented |
release; quality; validation |
Design Specifications¶
ID |
Title |
Status |
Links |
|---|---|---|---|
Release Agent & Automation |
implemented |
||
Git Tag Creation |
implemented |
||
GitHub Actions Workflow |
implemented |
REQ_REL_GITHUB_ACTIONS; REQ_REL_DOC_BUILD; REQ_REL_AGENT_TEST |
|
GitHub Pages Publishing |
implemented |
||
Release Notes Structure |
implemented |
||
Validation Checklist |
implemented |
REQ_REL_VALIDATION; REQ_REL_DOC_BUILD; REQ_REL_AGENT_TEST; SPEC_REL_GITHUB_ACTIONS |
|
Version Number Format |
implemented |
||
Release Workflow Orchestration |
implemented |
REQ_WF_RELEASE_SEQUENCE; REQ_REL_SEMVER; REQ_REL_VALIDATION; REQ_REL_GITHUB_PUBLISH |