coulomb/markitect-main
2
0
Fork 0
Code Issues 60 Pull Requests Actions 1 Projects 12 Releases 1 Wiki Activity

plan: create release-management-optimization roadmap topic

Browse Source 
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
This commit is contained in:
Bernd Worsch
2026-01-06 13:18:39 +01:00
parent 5e3646fdff
commit 4e9117ddcb
2 changed files with 643 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
roadmap/260106-release-management-optimization/README.md Normal file
View File

@@ -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** 🎯

604
roadmap/260106-release-management-optimization/WORKPLAN.md Normal file
View File

@@ -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<version>[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 <commit-hash> -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.