docs: add git status unpushed tags optimization

Added critical optimization #1 based on v0.10.0 release experience:

**Issue**: git status doesn't show unpushed tags, leading to forgotten tag pushes
**Impact**: v0.9.0 and v0.10.0 tags weren't pushed, plus older version tags
**Solution**: Enhanced release status or git hook to show unpushed tags

Total optimizations identified: 9 (was 8)
- High Priority: 4 (added unpushed tags visibility)
- Medium Priority: 3
- Low Priority: 2

Ready to implement all optimizations systematically.
This commit is contained in:
2026-01-06 17:22:09 +01:00
parent 75c8f8c325
commit bf4767d06b

View File

@@ -57,13 +57,51 @@
**Current Workaround**: Remember to run after creating schema
**Optimization**: Auto-detect and ingest schemas in build process
#### 6. Git Status Doesn't Show Unpushed Tags ⚠️
**Problem**: `git status` doesn't show tags that haven't been pushed to origin
**Impact**:
- Easy to forget to push tags after creating them
- No visibility into unpushed tags (v0.9.0, v0.10.0 weren't pushed until manually noticed)
- Tags from older versions also weren't pushed (discovered when pushing v0.10.0 tags)
**Current Workaround**: Manually check `git ls-remote --tags origin` vs `git tag -l`
**Optimization**: Enhanced git status or custom status command showing unpushed tags
---
## Optimization Opportunities
### High Priority (Would Have Helped v0.10.0)
#### 1. Automated Tag Pushing
#### 1. Git Status Enhancement for Unpushed Tags
**Current**:
```bash
git status
# On branch main
# Your branch is up to date with 'origin/main'.
# nothing to commit, working tree clean
# ^ No mention of unpushed tags!
```
**Optimized**:
```bash
release status
# OR: Enhanced git status via git hook
# Shows:
# - Current branch and commit status
# - Unpushed tags: v0.9.0, v0.10.0
# - Tags on origin vs local
# - Reminder to push tags
```
**Implementation Options**:
1. **Git post-commit hook**: Add .git/hooks/post-commit to check unpushed tags
2. **Enhanced `release status`**: Add tag comparison to release status command
3. **Git alias**: Create custom git alias for comprehensive status
**Estimated Effort**: 1 hour
**Impact**: Prevents forgotten tag pushes, immediate visibility
#### 2. Automated Tag Pushing
**Current**:
```bash
git tag -a v0.10.0 -m "..."
@@ -82,7 +120,7 @@ release tag v0.10.0
**Estimated Effort**: 1 hour
**Impact**: Prevents forgotten tag pushes
#### 2. CHANGELOG Validation in Release Flow
#### 3. CHANGELOG Validation in Release Flow
**Current**: Manual validation
```bash
markitect validate CHANGELOG.md --schema changelog-schema-v1.0.md --semantic
@@ -100,7 +138,7 @@ release validate
**Estimated Effort**: 2 hours
**Impact**: Catches CHANGELOG errors before release
#### 3. Version-Tag Consistency Check
#### 4. Version-Tag Consistency Check
**Current**: Manual verification that CHANGELOG version matches tag
**Optimized**:
@@ -119,7 +157,7 @@ release validate
### Medium Priority (Nice to Have)
#### 4. CHANGELOG Section Generation
#### 5. CHANGELOG Section Generation
**Current**: Manually create `## [X.Y.Z] - YYYY-MM-DD` section
**Optimized**:
@@ -136,7 +174,7 @@ release prepare v0.11.0
**Estimated Effort**: 3 hours
**Impact**: Reduces manual editing, prevents format errors
#### 5. Explicit Version Command
#### 6. Explicit Version Command
**Current**: `markitect --version`
**Optimized**:
@@ -153,7 +191,7 @@ markitect version
**Estimated Effort**: 30 minutes
**Impact**: Better UX, more detailed version info
#### 6. Release Summary Auto-Generation
#### 7. Release Summary Auto-Generation
**Current**: Manually created comprehensive summary
**Optimized**:
@@ -172,7 +210,7 @@ release summary v0.10.0
### Low Priority (Future Enhancements)
#### 7. Schema Auto-Ingestion
#### 8. Schema Auto-Ingestion
**Current**: Manual `schema-ingest` after creating schema
**Optimized**: Automatically detect new/updated schemas during build
@@ -180,7 +218,7 @@ release summary v0.10.0
**Estimated Effort**: 1 hour
**Impact**: Reduces manual steps
#### 8. Release Notes from CHANGELOG
#### 9. Release Notes from CHANGELOG
**Current**: Copy CHANGELOG section manually
**Optimized**:
@@ -276,12 +314,13 @@ Keep release process as-is, focus on new work
- **Total**: ~3 hours
**Manual Steps**: 8 steps
**Potential Automation**: 5 steps (tags, validation, version cmd, summary gen, schema ingest)
**Potential Automation**: 6 steps (tag status, tags, validation, version cmd, summary gen, schema ingest)
**Error Rate**:
- Forgot to push tags: 1 error
- Version detection bugs: 1 error (fixed in Stage 1)
- CHANGELOG format: 0 errors (schema caught issues)
- Unpushed tags visibility: 1 critical issue (no git status warning)
### With Stage 3 Optimizations