From 4e9117ddcb4d646ba6ba23c1f45d2b635bf48f3e Mon Sep 17 00:00:00 2001 From: tegwick Date: Tue, 6 Jan 2026 13:18:39 +0100 Subject: [PATCH] plan: create release-management-optimization roadmap topic Created comprehensive staged workplan for enhancing release management infrastructure with robust validation using the schema system. **Critical Issues Identified**: - setuptools-scm missing tag_regex configuration - markitect --version returns 'unknown' instead of actual version - CHANGELOG shows v0.9.0 (2025-11-14) but git tag never created - No validation for CHANGELOG format or version-tag consistency **Solution Approach**: Create changelog-schema-v1.0.md to validate Keep a Changelog format, demonstrating schema evolution in real-world use case. **Staged Workplan**: - Stage 1 (45 min): Critical fixes to unblock v0.10.0 release - Stage 2 (2.5 hrs): CHANGELOG schema creation and validation - Stage 3 (2 hrs): Release capability enhancements - Stage 4 (optional): Schema system extensions **Showcase Feature**: 'The release that validates itself' - v0.10.0 uses its own schema system to validate its CHANGELOG - Perfect demonstration of schema evolution practical value **Next Version**: v0.10.0 (not v0.9.0) - CHANGELOG already shows v0.9.0 as released - Must maintain version history integrity --- .../README.md | 39 ++ .../WORKPLAN.md | 604 ++++++++++++++++++ 2 files changed, 643 insertions(+) create mode 100644 roadmap/260106-release-management-optimization/README.md create mode 100644 roadmap/260106-release-management-optimization/WORKPLAN.md diff --git a/roadmap/260106-release-management-optimization/README.md b/roadmap/260106-release-management-optimization/README.md new file mode 100644 index 00000000..1d57d016 --- /dev/null +++ b/roadmap/260106-release-management-optimization/README.md @@ -0,0 +1,39 @@ +# Release Management Optimization + +**Created**: 2026-01-06 +**Status**: Planning → Ready to implement +**Priority**: High (blocks v0.10.0 release) + +## Quick Summary + +Enhance release management with robust validation using the schema system we just built. Creates a perfect showcase: **validate CHANGELOG.md with a changelog schema**. + +## Critical Issues Found + +1. **setuptools-scm bug**: Missing tag_regex → `markitect --version` returns "unknown" +2. **Missing v0.9.0 tag**: CHANGELOG says v0.9.0 released but git tag never created +3. **No validation**: No checks for CHANGELOG format or version-tag consistency + +## Solution + +Create **changelog-schema-v1.0.md** to validate Keep a Changelog format, integrate into release workflow. Demonstrates schema evolution in action! + +## Staged Approach + +- **Stage 1** (45 min): Critical fixes → unblock v0.10.0 release +- **Stage 2** (2.5 hrs): CHANGELOG schema → showcase feature +- **Stage 3** (2 hrs): Release tooling enhancements +- **Stage 4** (optional): Schema extensions (hooks/agents) + +**Recommended**: Standard Track (Stages 1-3) = 5 hours for production-ready release management + +## Files + +- `WORKPLAN.md` - Detailed staged implementation plan +- `DONE.md` - Completion checklist (when finished) + +## Philosophy + +> "Use the tools we build to improve the tools we build." + +Release v0.10.0 becomes: **The release that validates itself** 🎯 diff --git a/roadmap/260106-release-management-optimization/WORKPLAN.md b/roadmap/260106-release-management-optimization/WORKPLAN.md new file mode 100644 index 00000000..c01495da --- /dev/null +++ b/roadmap/260106-release-management-optimization/WORKPLAN.md @@ -0,0 +1,604 @@ +# Release Management Optimization Workplan + +**Topic**: 260106-release-management-optimization +**Created**: 2026-01-06 +**Status**: Planning +**Priority**: High (blocks v0.10.0 release) + +--- + +## Overview + +Enhance release management infrastructure with robust validation and automation, using the newly built schema system. This creates a practical showcase for the schema evolution capabilities while fixing critical release tooling issues. + +## Motivation + +### Current Issues + +1. **setuptools-scm Configuration Bug** + - Missing tag regex filter → picks up non-version tags + - Result: `markitect --version` returns "unknown" + - Impact: Users can't verify installed version + +2. **Version History Inconsistency** + - CHANGELOG shows v0.9.0 (2025-11-14) but git tag never created + - setuptools-scm sees v0.8.0 as latest + - 109 commits between v0.8.0 and current + +3. **No Validation Infrastructure** + - No CHANGELOG validation (format, version consistency) + - No pre-release checks for version/tag alignment + - No automated version bump validation + +4. **Missing CLI Features** + - No explicit `markitect --version` command + - Version info only via __version__.py fallback + +### Opportunity: Schema System Showcase + +Creating a **CHANGELOG schema** demonstrates: +- Real-world use of x-markitect extensions +- Schema validation for structured markdown +- Section classification (Unreleased, versioned releases) +- Content patterns (Keep a Changelog format) +- Integration with release tooling + +**Perfect timing**: Release v0.10.0 with the tool that validates its own changelog! + +--- + +## Goals + +### Primary +1. ✅ **Fix setuptools-scm configuration** (blocks release) +2. ✅ **Restore version history** (retroactive v0.9.0 tag) +3. ✅ **Create CHANGELOG schema** (Keep a Changelog format) +4. ✅ **Implement CHANGELOG validation** (pre-release check) + +### Secondary +5. ⭐ **Add explicit version command** to markitect CLI +6. ⭐ **Extend schema system** (if needed for system calls/agents) +7. ⭐ **Release capability enhancements** (validation hooks) + +### Stretch +8. 🎯 **Git tag validation** (ensure CHANGELOG ↔ tags sync) +9. 🎯 **Automated version bumping** suggestions +10. 🎯 **Release notes generation** from CHANGELOG + +--- + +## Staged Workplan + +### Stage 1: Critical Fixes (Required for v0.10.0) + +**Goal**: Unblock immediate release + +#### Task 1.1: Fix setuptools-scm Configuration +**File**: `pyproject.toml` + +**Current**: +```toml +[tool.setuptools_scm] +write_to = "markitect/_version.py" +``` + +**Updated**: +```toml +[tool.setuptools_scm] +write_to = "markitect/_version.py" +version_scheme = "python-simplified-semver" +tag_regex = "^v(?P[0-9]+\\.[0-9]+\\.[0-9]+)$" +local_scheme = "no-local-version" +``` + +**Validation**: +- Run `python -c "from setuptools_scm import get_version; print(get_version())"` +- Should show `0.8.1.dev109+g5e3646f` (or similar, based on v0.8.0 tag) +- Run `markitect --version` → should show version (after reinstall) + +**Estimated**: 10 minutes + +#### Task 1.2: Restore Version History +**Action**: Retroactively create v0.9.0 tag + +**Find v0.9.0 release commit**: +```bash +# Find commit around 2025-11-14 with plugin/rendering changes +git log --since="2025-11-13" --until="2025-11-15" --oneline +``` + +**Create tag**: +```bash +# Tag the identified commit +git tag -a v0.9.0 -m "Release v0.9.0: Plugin infrastructure and TestDrive JSUI + +- Plugin Infrastructure Foundation +- RenderingEngineManager +- TestDrive JSUI Plugin +- ChatGPT Document Theme +- CLI Engine Parameter + +See CHANGELOG.md for full details." +``` + +**Validation**: +- `git tag -l 'v*'` → should show v0.9.0 +- `git describe --tags --match='v*'` → should show v0.9.0-based description + +**Estimated**: 15 minutes + +#### Task 1.3: Prepare v0.10.0 Release +**File**: `CHANGELOG.md` + +**Actions**: +1. Move Unreleased content to v0.10.0 section +2. Add release date +3. Verify version links at bottom + +**Format**: +```markdown +## [Unreleased] + +## [0.10.0] - 2026-01-06 + +### Added +- **ADR Schema**: Architecture Decision Record validation schema + - 12 section classifications for comprehensive ADR structure + - Content pattern validation for formatting rules + - Quality metrics for completeness +- **Markdown Schema Support**: Fixed validate and generate-stub commands + - load_schema_from_path() supports .json and .md files + - DocumentWrapper extracts headings from AST + - All schema commands now work with markdown schemas +- **Schema Evolution Topic Closure**: Complete Phase 1-3 implementation + - 5 production schemas (manpage, API docs, terminology, schema-schema, ADR) + - Semantic validation system fully operational + - Template generation working with schemas + +### Fixed +- setuptools-scm configuration with tag_regex for proper version detection +- markitect --version now returns correct version instead of "unknown" +- Semantic validator AST heading extraction via DocumentWrapper + +[Unreleased]: https://github.com/worsch/markitect/compare/v0.10.0...HEAD +[0.10.0]: https://github.com/worsch/markitect/compare/v0.9.0...v0.10.0 +``` + +**Estimated**: 20 minutes + +**Total Stage 1**: ~45 minutes + +--- + +### Stage 2: CHANGELOG Schema (Showcase Feature) + +**Goal**: Create and validate CHANGELOG schema using schema evolution infrastructure + +#### Task 2.1: Analyze CHANGELOG Structure +**Method**: Study Keep a Changelog format + +**Structure to validate**: +```markdown +# Changelog + +[preamble text] + +## [Unreleased] +### Added / Changed / Deprecated / Removed / Fixed / Security +- Bullet points + +## [X.Y.Z] - YYYY-MM-DD +### Added / Changed / Deprecated / Removed / Fixed / Security +- Bullet points + +[version links at bottom] +``` + +**Schema Requirements**: +- **Sections**: Unreleased (required), Version sections (pattern: `[X.Y.Z]`) +- **Subsections**: Added/Changed/Deprecated/Removed/Fixed/Security (optional) +- **Content Patterns**: + - Version format: `\[(\d+\.\d+\.\d+)\]` + - Date format: `YYYY-MM-DD` + - Links at bottom: `[version]: url` +- **Quality Metrics**: + - Each version should have at least one subsection + - Bullet points required in subsections + +**Estimated**: 30 minutes + +#### Task 2.2: Create changelog-schema-v1.0.md +**File**: `markitect/schemas/changelog-schema-v1.0.md` + +**Schema structure**: +```markdown +--- +schema-id: "https://markitect.dev/schemas/changelog/v1.0" +version: "1.0.0" +status: "stable" +domain: "changelog" +description: "JSON schema for Keep a Changelog format with version history validation" +--- + +# Changelog Schema v1.0 + +## Overview +This schema validates CHANGELOG.md files following the Keep a Changelog format... + +## Schema Definition +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "x-markitect-sections": { + "Unreleased": { + "classification": "required", + "heading_level": 2, + "error_message": "Unreleased section is mandatory for tracking upcoming changes" + }, + // Version sections validated via pattern + }, + "x-markitect-content-control": { + "unreleased": { + "content_quality": { + "min_words": 0 // Can be empty + } + }, + // Version sections with date validation + } +} +``` +``` + +**Considerations for Extension**: +- **System Call Validation**: Check git tags match CHANGELOG versions + - `x-markitect-validation-hooks`: { "system": "git tag -l 'v*'" } + - Requires schema system extension + +- **Agent Validation**: Use AI to validate version consistency + - `x-markitect-validation-agents`: { "prompt": "Check versions align" } + - Requires agent integration + +**Decision**: Start with pure schema validation, add hooks/agents if needed + +**Estimated**: 90 minutes + +#### Task 2.3: Ingest and Test CHANGELOG Schema +**Commands**: +```bash +# Ingest +markitect schema-ingest markitect/schemas/changelog-schema-v1.0.md + +# Validate our CHANGELOG +markitect validate CHANGELOG.md --schema changelog-schema-v1.0.md +``` + +**Expected**: +- Section validation: Unreleased section present ✓ +- Version format validation: All versions follow X.Y.Z ✓ +- Date validation: ISO format YYYY-MM-DD ✓ +- Content structure: Subsections present ✓ + +**Fix any issues found in CHANGELOG.md** + +**Estimated**: 30 minutes + +**Total Stage 2**: ~2.5 hours + +--- + +### Stage 3: Release Capability Enhancements + +**Goal**: Integrate CHANGELOG validation into release workflow + +#### Task 3.1: Add CHANGELOG Validation to Release Manager +**File**: `capabilities/release-management/src/release_management/core/manager.py` + +**Add validation method**: +```python +def validate_changelog(self) -> tuple[bool, list[str]]: + """Validate CHANGELOG.md against changelog schema.""" + from markitect.cli import validate_against_schema + + changelog_path = self.project_root / "CHANGELOG.md" + schema_path = self.project_root / "markitect/schemas/changelog-schema-v1.0.md" + + if not changelog_path.exists(): + return False, ["CHANGELOG.md not found"] + + is_valid = validate_against_schema(changelog_path, schema_path) + if not is_valid: + return False, ["CHANGELOG.md validation failed"] + + return True, [] +``` + +**Integrate into validate_release_state()**: +```python +def validate_release_state(self) -> tuple[bool, list[str]]: + issues = [] + + # Existing validations... + + # Add CHANGELOG validation + changelog_valid, changelog_issues = self.validate_changelog() + if not changelog_valid: + issues.extend(changelog_issues) + + return len(issues) == 0, issues +``` + +**Estimated**: 45 minutes + +#### Task 3.2: Add Version-Tag Consistency Check +**Feature**: Verify CHANGELOG versions match git tags + +**Method**: +```python +def check_version_tag_consistency(self) -> tuple[bool, list[str]]: + """Check CHANGELOG versions have corresponding git tags.""" + import re + + # Parse CHANGELOG for versions + changelog = (self.project_root / "CHANGELOG.md").read_text() + versions = re.findall(r'## \[(\d+\.\d+\.\d+)\]', changelog) + + # Get git tags + result = subprocess.run(['git', 'tag', '-l', 'v*'], + capture_output=True, text=True) + tags = result.stdout.strip().split('\n') + tag_versions = [t.lstrip('v') for t in tags if t.startswith('v')] + + # Check consistency + issues = [] + for version in versions: + if version not in tag_versions: + issues.append(f"CHANGELOG version {version} has no git tag v{version}") + + return len(issues) == 0, issues +``` + +**Estimated**: 45 minutes + +#### Task 3.3: Add Explicit Version Command +**File**: `markitect/cli.py` + +**Add command**: +```python +@cli.command() +def version(): + """Display detailed version information.""" + from markitect.__version__ import get_version_info + + info = get_version_info() + + click.echo(f"MarkiTect {info['full_version']}") + click.echo(f"Git Commit: {info['git_commit']}") + click.echo(f"Git Branch: {info['git_branch']}") + + if info['is_dev']: + click.echo("⚠️ Development version (not released)") + else: + click.echo(f"✅ Released version") +``` + +**Update --version option**: +```python +@click.version_option(version=get_version(), prog_name="markitect") +def cli(): + ... +``` + +**Estimated**: 30 minutes + +**Total Stage 3**: ~2 hours + +--- + +### Stage 4: Schema System Extensions (If Needed) + +**Goal**: Add validation hooks for system calls and agents + +**Only implement if pure schema validation insufficient** + +#### Option A: System Call Hooks +**Extension**: `x-markitect-validation-hooks` + +```json +{ + "x-markitect-validation-hooks": { + "pre-validation": [ + { + "name": "check-git-tags", + "command": "git tag -l 'v*'", + "parser": "lines", + "validation": { + "min_count": 5, + "pattern": "^v\\d+\\.\\d+\\.\\d+$" + } + } + ] + } +} +``` + +**Implementation**: +- Add HookValidator to validators package +- Execute system commands securely +- Parse and validate output +- Integrate into SemanticValidator + +**Estimated**: 3 hours + +#### Option B: Agent Validation +**Extension**: `x-markitect-validation-agents` + +```json +{ + "x-markitect-validation-agents": { + "consistency-check": { + "prompt": "Verify all CHANGELOG versions have corresponding git tags", + "context": ["CHANGELOG.md", "git tag -l"], + "severity": "warning" + } + } +} +``` + +**Implementation**: +- Add AgentValidator to validators package +- Integration with LLM/agent framework +- Structured output parsing +- Integrate into SemanticValidator + +**Estimated**: 4 hours + +**Decision Point**: Only proceed if needed for CHANGELOG validation + +**Total Stage 4**: 0-7 hours (conditional) + +--- + +## Success Criteria + +### Stage 1 (Required for Release) +- ✅ `markitect --version` returns actual version (not "unknown") +- ✅ v0.9.0 git tag exists +- ✅ CHANGELOG.md has v0.10.0 section +- ✅ v0.10.0 ready for tagging + +### Stage 2 (Showcase Feature) +- ✅ changelog-schema-v1.0.md created and ingested +- ✅ CHANGELOG.md validates against schema +- ✅ Schema demonstrates Keep a Changelog format validation + +### Stage 3 (Enhanced Tooling) +- ✅ Release validation includes CHANGELOG check +- ✅ Version-tag consistency checking works +- ✅ `markitect version` command available + +### Stage 4 (Optional Extensions) +- ⭐ System call hooks functional (if implemented) +- ⭐ Agent validation working (if implemented) + +--- + +## Timeline Estimate + +### Fast Track (Stage 1 Only) +- **Time**: 45 minutes +- **Scope**: Critical fixes for v0.10.0 release +- **Result**: Can release immediately + +### Standard Track (Stages 1-3) +- **Time**: 5 hours +- **Scope**: Fixes + CHANGELOG schema + tooling enhancements +- **Result**: Production-ready release management + +### Full Track (Stages 1-4) +- **Time**: 5-12 hours (depends on extensions needed) +- **Scope**: Complete system with validation hooks/agents +- **Result**: Advanced validation infrastructure + +--- + +## Decision Points + +### 1. Release Strategy +**Options**: +- A. Fast track → Release v0.10.0 now with Stage 1 fixes only +- B. Standard track → Complete Stages 1-3, release as v0.10.1 or v0.11.0 +- C. Full track → Include Stage 4, major release v1.0.0 + +**Recommendation**: **Option B (Standard Track)** +- Showcases schema system with real use case +- Improves release tooling robustly +- Reasonable timeline (5 hours) +- Release as **v0.10.0** with all features + +### 2. Schema Extensions +**When to implement**: +- Stage 4 only if pure schema validation can't handle: + - Git tag checking (may need system call hook) + - Version consistency (may need agent validation) + +**Recommendation**: **Start without extensions** +- Try pure schema validation first +- Add hooks/agents only if needed +- Document extension needs for future enhancement + +### 3. release-management Extraction +**Question**: Make it a git submodule? + +**Current**: Regular directory (not extracted) + +**Recommendation**: **Defer to future** +- Not blocking for release +- Works fine as capability +- Can extract later if needed for reuse + +--- + +## Files to Create/Modify + +### Create +- `markitect/schemas/changelog-schema-v1.0.md` - CHANGELOG validation schema +- `roadmap/260106-release-management-optimization/DONE.md` - Completion checklist (when done) + +### Modify +- `pyproject.toml` - Fix setuptools-scm configuration +- `CHANGELOG.md` - Add v0.10.0 section, fix format if needed +- `markitect/cli.py` - Add explicit version command +- `capabilities/release-management/src/release_management/core/manager.py` - Add CHANGELOG validation +- (Optional) `markitect/validators/` - Add hook/agent validators if needed + +### Git Operations +- Create v0.9.0 tag retroactively +- Create v0.10.0 tag for release + +--- + +## Risks & Mitigations + +### Risk 1: Retroactive Tagging +**Issue**: Creating v0.9.0 tag retroactively might confuse users + +**Mitigation**: +- Document in CHANGELOG that tag was missing +- Use tag message to explain retroactive creation +- Don't publish v0.9.0 packages (already past that release) + +### Risk 2: Schema Extensions Complexity +**Issue**: Implementing hooks/agents might be complex + +**Mitigation**: +- Start with pure schema validation +- Only add extensions if necessary +- Document extension API for future + +### Risk 3: CHANGELOG Format Variations +**Issue**: Real-world CHANGELOGs may not match Keep a Changelog exactly + +**Mitigation**: +- Make schema flexible with optional sections +- Use warnings instead of errors for style issues +- Support alternative section names + +--- + +## Next Steps + +1. **Review this workplan** with user +2. **Choose release strategy** (Fast/Standard/Full track) +3. **Begin Stage 1** (critical fixes) +4. **Proceed based on chosen track** + +--- + +## Notes + +- This workplan creates a **perfect showcase** for schema evolution +- Validates its own CHANGELOG with the schema system it just built +- Real-world practical application demonstrating value +- Release v0.10.0 becomes a milestone: "The release that validates itself" + +**Philosophy**: Use the tools we build to improve the tools we build.