Add release management system and prepare v1.0.0 publication

- Add agent-releaseManager.md with comprehensive publication workflow guidance - Add 6 release- prefixed make targets for structured release process: - release-check: Validate release readiness - release-prepare: Build packages and prepare release - release-test: Test publication via TestPyPI - release-publish: Publish to production PyPI - release-finalize: Post-release tasks (tags, GitHub releases) - release-rollback: Emergency rollback procedures - Update pyproject.toml version from 0.1.0 to 1.0.0 for consistency with CHANGELOG.md - Update installation documentation in README.md and GETTING_STARTED.md - Add current "from source" installation instructions - Maintain "from PyPI" instructions for post-publication - Framework now ready for v1.0.0 publication with complete release workflow 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-19 13:42:32 +02:00
parent de94036e35
commit 30daabf12c
5 changed files with 331 additions and 5 deletions
--- a/198
+++ b/198
@@ -1,6 +1,6 @@
 # Makefile for Kaizen Agentic development tasks

-.PHONY: help setup-complete setup-structure setup-python setup-tools setup-docs setup-tests setup-verify ensure-project-structure install-dev standards-check standards-fix standards-test test test-all build clean lint format venv-status agents-list agents-update agents-validate agents-status agents-install-cli
+.PHONY: help setup-complete setup-structure setup-python setup-tools setup-docs setup-tests setup-verify ensure-project-structure install-dev standards-check standards-fix standards-test test test-all build clean lint format venv-status agents-list agents-update agents-validate agents-status agents-install-cli release-check release-prepare release-test release-publish release-finalize release-rollback

 # Variables
 VENV = .venv
@@ -38,6 +38,14 @@ help:
 	@echo "  agents-status   - Show agent status and project info"
 	@echo "  agents-install-cli - Install kaizen-agentic CLI tool"
 	@echo ""
+	@echo "Release Management:"
+	@echo "  release-check   - Validate release readiness (tests, linting, version consistency)"
+	@echo "  release-prepare - Prepare release (update versions, build packages)"
+	@echo "  release-test    - Test publication workflow using TestPyPI"
+	@echo "  release-publish - Publish to production PyPI"
+	@echo "  release-finalize - Post-release tasks (tags, GitHub release, documentation)"
+	@echo "  release-rollback - Emergency rollback procedures"
+	@echo ""
 	@echo "Development:"
 	@echo "  test        - Run unit tests only (fast)"
 	@echo "  test-all    - Run comprehensive test suite (tests + standards + quality)"
@@ -708,4 +716,190 @@ agents-install-cli: $(VENV)/bin/activate
 	@$(VENV_PIP) install --upgrade pip
 	@$(VENV_PIP) install -e .
 	@echo "✅ CLI installed. Use 'kaizen-agentic --help' for usage."
-	@echo "💡 Activate virtual environment with: source $(VENV)/bin/activate"
+	@echo "💡 Activate virtual environment with: source $(VENV)/bin/activate"
+
+# ============================================================================
+# Release Management Targets
+# ============================================================================
+
+# Validate release readiness (tests, linting, version consistency)
+release-check: $(VENV)/bin/activate
+	@echo "🔍 Validating release readiness..."
+	@echo ""
+	@ISSUES=0; \
+	echo "📋 Release Readiness Checklist:"; \
+	echo "==============================="; \
+	echo "  • Version Consistency:"; \
+	CHANGELOG_VERSION=$$(grep '^## \[' CHANGELOG.md | head -1 | sed 's/## \[\(.*\)\].*/\1/' | grep -v "Unreleased" || echo ""); \
+	PYPROJECT_VERSION=$$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/' || echo ""); \
+	if [ "$$CHANGELOG_VERSION" = "$$PYPROJECT_VERSION" ] && [ -n "$$CHANGELOG_VERSION" ]; then \
+		echo "    ✅ Versions consistent: $$CHANGELOG_VERSION"; \
+	else \
+		echo "    ❌ Version mismatch: CHANGELOG.md='$$CHANGELOG_VERSION', pyproject.toml='$$PYPROJECT_VERSION'"; \
+		ISSUES=$$((ISSUES + 1)); \
+	fi; \
+	echo "  • Code Quality:"; \
+	if $(VENV_PYTHON) -m flake8 src/ --max-line-length=100 >/dev/null 2>&1; then \
+		echo "    ✅ Code passes linting"; \
+	else \
+		echo "    ❌ Code has linting violations"; \
+		ISSUES=$$((ISSUES + 1)); \
+	fi; \
+	echo "  • Test Suite:"; \
+	if $(VENV_PYTHON) -m pytest tests/ --tb=no -q >/dev/null 2>&1; then \
+		echo "    ✅ All tests pass"; \
+	else \
+		echo "    ❌ Tests failing"; \
+		ISSUES=$$((ISSUES + 1)); \
+	fi; \
+	echo "  • Documentation:"; \
+	if [ -f "README.md" ] && [ -f "CHANGELOG.md" ] && [ -f "docs/GETTING_STARTED.md" ]; then \
+		echo "    ✅ Core documentation exists"; \
+	else \
+		echo "    ❌ Missing core documentation files"; \
+		ISSUES=$$((ISSUES + 1)); \
+	fi; \
+	echo "  • Build System:"; \
+	if [ -f "pyproject.toml" ] && grep -q '^\[build-system\]' pyproject.toml; then \
+		echo "    ✅ Build configuration present"; \
+	else \
+		echo "    ❌ Build system not configured"; \
+		ISSUES=$$((ISSUES + 1)); \
+	fi; \
+	echo ""; \
+	if [ $$ISSUES -eq 0 ]; then \
+		echo "✅ Release readiness: PASSED"; \
+		echo "   Ready for release preparation."; \
+	else \
+		echo "❌ Release readiness: FAILED ($$ISSUES issues)"; \
+		echo "   Fix issues before proceeding with release."; \
+		exit 1; \
+	fi
+
+# Prepare release (update versions, build packages)
+release-prepare: release-check clean
+	@echo "🏗️  Preparing release..."
+	@echo ""
+	@VERSION=$$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/'); \
+	echo "📦 Building packages for version $$VERSION..."; \
+	$(VENV_PYTHON) -c "import build" 2>/dev/null || $(VENV_PIP) install build; \
+	$(VENV_PYTHON) -m build; \
+	echo ""; \
+	echo "✅ Release preparation completed:"; \
+	echo "   • Version: $$VERSION"; \
+	echo "   • Packages built in dist/"; \
+	ls -la dist/ | grep "$$VERSION" || echo "   • Package files:"; ls -la dist/; \
+	echo ""; \
+	echo "💡 Next steps:"; \
+	echo "   • Run 'make release-test' to test publication"; \
+	echo "   • Run 'make release-publish' for production release"
+
+# Test publication workflow using TestPyPI
+release-test: release-prepare
+	@echo "🧪 Testing publication workflow with TestPyPI..."
+	@echo ""
+	@VERSION=$$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/'); \
+	echo "🚀 Uploading to TestPyPI (version $$VERSION)..."; \
+	$(VENV_PYTHON) -c "import twine" 2>/dev/null || $(VENV_PIP) install twine; \
+	echo ""; \
+	echo "⚠️  Manual Step Required:"; \
+	echo "   Run the following command to upload to TestPyPI:"; \
+	echo "   $(VENV_PYTHON) -m twine upload --repository testpypi dist/*"; \
+	echo ""; \
+	echo "   Then test installation:"; \
+	echo "   pip install --index-url https://test.pypi.org/simple/ kaizen-agentic==$$VERSION"; \
+	echo ""; \
+	echo "💡 Configure TestPyPI credentials:"; \
+	echo "   • Create account at https://test.pypi.org/"; \
+	echo "   • Generate API token"; \
+	echo "   • Store in ~/.pypirc or use keyring"
+
+# Publish to production PyPI
+release-publish: release-check
+	@echo "🚀 Publishing to production PyPI..."
+	@echo ""
+	@VERSION=$$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/'); \
+	echo "⚠️  PRODUCTION RELEASE WARNING ⚠️"; \
+	echo "   About to publish version $$VERSION to PyPI"; \
+	echo "   This action cannot be undone!"; \
+	echo ""; \
+	echo "📋 Pre-flight checklist:"; \
+	echo "   ✅ All tests pass"; \
+	echo "   ✅ Documentation updated"; \
+	echo "   ✅ Version tagged in git"; \
+	echo "   ✅ TestPyPI upload tested"; \
+	echo ""; \
+	$(VENV_PYTHON) -c "import twine" 2>/dev/null || $(VENV_PIP) install twine; \
+	echo "⚠️  Manual Step Required:"; \
+	echo "   Run the following command to publish:"; \
+	echo "   $(VENV_PYTHON) -m twine upload dist/*"; \
+	echo ""; \
+	echo "💡 Configure PyPI credentials:"; \
+	echo "   • Create account at https://pypi.org/"; \
+	echo "   • Generate API token"; \
+	echo "   • Store in ~/.pypirc or use keyring"
+
+# Post-release tasks (tags, GitHub release, documentation)
+release-finalize: $(VENV)/bin/activate
+	@echo "🏁 Finalizing release..."
+	@echo ""
+	@VERSION=$$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/'); \
+	echo "📝 Post-release tasks for version $$VERSION:"; \
+	echo ""; \
+	echo "  • Git Tagging:"; \
+	if git tag -l | grep -q "^v$$VERSION$$"; then \
+		echo "    ✅ Tag v$$VERSION already exists"; \
+	else \
+		echo "    📌 Creating git tag v$$VERSION..."; \
+		git tag -a "v$$VERSION" -m "Release version $$VERSION"; \
+		echo "    ✅ Tag created"; \
+	fi; \
+	echo ""; \
+	echo "  • GitHub Release:"; \
+	echo "    💡 Manual steps required:"; \
+	echo "       1. Push tags: git push origin v$$VERSION"; \
+	echo "       2. Create GitHub release at:"; \
+	echo "          https://github.com/kaizen-agentic/kaizen-agentic/releases/new"; \
+	echo "       3. Upload dist/ files as release assets"; \
+	echo ""; \
+	echo "  • Documentation:"; \
+	echo "    💡 Verify installation instructions work:"; \
+	echo "       pip install kaizen-agentic==$$VERSION"; \
+	echo ""; \
+	echo "✅ Release finalization checklist provided"; \
+	echo "   Complete manual steps above to finish release process"
+
+# Emergency rollback procedures
+release-rollback: $(VENV)/bin/activate
+	@echo "🚨 Emergency release rollback procedures..."
+	@echo ""
+	@echo "⚠️  ROLLBACK PROCEDURES ⚠️"; \
+	echo "================================"; \
+	echo ""; \
+	echo "📋 Available rollback options:"; \
+	echo ""; \
+	echo "  1. PyPI Package Yanking:"; \
+	echo "     • Cannot delete published packages"; \
+	echo "     • Can 'yank' versions to prevent new installs"; \
+	echo "     • Use PyPI web interface or twine"; \
+	echo ""; \
+	echo "  2. Git Rollback:"; \
+	echo "     • Revert commits: git revert <commit-hash>"; \
+	echo "     • Delete tags: git tag -d v<version>"; \
+	echo "     • Force push (if no external users)"; \
+	echo ""; \
+	echo "  3. Documentation Updates:"; \
+	echo "     • Update CHANGELOG.md with rollback notice"; \
+	echo "     • Add deprecation warnings"; \
+	echo "     • Publish corrected documentation"; \
+	echo ""; \
+	echo "  4. Emergency Release:"; \
+	echo "     • Increment patch version"; \
+	echo "     • Fix critical issues"; \
+	echo "     • Fast-track through release process"; \
+	echo ""; \
+	echo "💡 Prevention for next time:"; \
+	echo "   • Always test with TestPyPI first"; \
+	echo "   • Use staging/preview environments"; \
+	echo "   • Implement automated quality gates"; \
+	echo "   • Consider pre-release versions for testing"
--- a/README.md
+++ b/README.md
@@ -7,8 +7,19 @@ This project embraces the Japanese concept of "kaizen" (continuous improvement)
 ## Quick Start

 ### Install the Package
+
+**From Source (Current - Development Version):**
 ```bash
-pip install kaizen-agentic
+git clone https://github.com/kaizen-agentic/kaizen-agentic.git
+cd kaizen-agentic
+make setup-complete
+make agents-install-cli
+source .venv/bin/activate
+```
+
+**From PyPI (Coming Soon):**
+```bash
+pip install kaizen-agentic  # Available after v1.0.0 publication
 ```

 ### Your First Project (New Users)
--- a/agents/agent-releaseManager.md
+++ b/agents/agent-releaseManager.md
@@ -0,0 +1,101 @@
+---
+name: releaseManager
+category: project-management
+description: Manages software releases, version control, and publication workflows for Python packages
+dependencies: []
+---
+
+# Release Manager Agent
+
+You are a specialized release management agent focused on Python package publication workflows, version control, and release automation.
+
+## Core Responsibilities
+
+### Version Management
+- **Semantic Versioning**: Ensure proper semantic versioning (MAJOR.MINOR.PATCH) compliance
+- **Version Synchronization**: Keep versions consistent across pyproject.toml, CHANGELOG.md, and documentation
+- **Release Notes**: Generate comprehensive release notes from CHANGELOG.md entries
+- **Tag Management**: Create and manage git tags for releases
+
+### Publication Workflow
+- **Package Building**: Build distribution packages (sdist and wheel) using modern Python tools
+- **Quality Assurance**: Run comprehensive tests and validation before publication
+- **PyPI Publication**: Handle TestPyPI and production PyPI uploads with proper authentication
+- **Post-Release Tasks**: Update documentation, create GitHub releases, and notify stakeholders
+
+### Documentation Updates
+- **Installation Instructions**: Update installation guides to reflect publication status
+- **Version References**: Ensure all documentation references correct versions
+- **Migration Guides**: Create migration guides for breaking changes
+- **Release Communication**: Draft release announcements and update project status
+
+## Release Types
+
+### Pre-Release (Alpha/Beta/RC)
+- Use for testing publication workflow
+- Publish to TestPyPI first
+- Version format: 1.0.0a1, 1.0.0b1, 1.0.0rc1
+
+### Production Release
+- Full validation and testing required
+- Publish to production PyPI
+- Create GitHub releases with assets
+- Update all documentation
+
+### Patch Releases
+- Hotfixes and critical bug fixes
+- Minimal documentation updates
+- Fast-track publication process
+
+## Make Target Structure
+
+Provide these release- prefixed make targets:
+
+- `release-check`: Validate release readiness (tests, linting, version consistency)
+- `release-prepare`: Prepare release (update versions, build packages)
+- `release-test`: Test publication workflow using TestPyPI
+- `release-publish`: Publish to production PyPI
+- `release-finalize`: Post-release tasks (tags, GitHub release, documentation)
+- `release-rollback`: Emergency rollback procedures
+
+## Best Practices
+
+### Pre-Release Checklist
+1. All tests passing
+2. Documentation updated
+3. CHANGELOG.md entries complete
+4. Version numbers synchronized
+5. Dependencies validated
+6. Security scan clean
+
+### Publication Security
+- Use API tokens, never passwords
+- Separate TestPyPI and production credentials
+- Validate package contents before upload
+- Monitor for supply chain attacks
+
+### Communication
+- Clear release notes
+- Breaking change notifications
+- Deprecation warnings with timelines
+- Community update posts
+
+## Integration Points
+
+### CI/CD Systems
+- GitHub Actions workflow integration
+- Automated testing on multiple Python versions
+- Security scanning and dependency checking
+- Automated documentation deployment
+
+### Monitoring
+- Download statistics tracking
+- Error rate monitoring
+- User feedback collection
+- Dependency vulnerability scanning
+
+When managing releases, always prioritize:
+1. **Security**: Never compromise on security practices
+2. **Reliability**: Thorough testing before publication
+3. **Communication**: Clear documentation and announcements
+4. **Reproducibility**: Consistent and documented processes
--- a/docs/GETTING_STARTED.md
+++ b/docs/GETTING_STARTED.md
@@ -8,11 +8,31 @@ This guide walks you through using Kaizen Agentic agents in any project, from in

 ### 1. Install the Package

+**Option A: From Source (Current - Development Version)**
+
 ```bash
+# Clone the repository
+git clone https://github.com/kaizen-agentic/kaizen-agentic.git
+cd kaizen-agentic
+
+# Set up development environment
+make setup-complete
+
+# Install CLI tool
+make agents-install-cli
+
+# Activate virtual environment
+source .venv/bin/activate
+```
+
+**Option B: From PyPI (Coming Soon)**
+
+```bash
+# Will be available once v1.0.0 is published
 pip install kaizen-agentic
 ```

-This gives you the `kaizen-agentic` command globally.
+> **📦 Release Status**: v1.0.0 is ready for publication. See our [release workflow](../Makefile) with `make release-*` targets.

 ### 2. Verify Installation

--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

 [project]
 name = "kaizen-agentic"
-version = "0.1.0"
+version = "1.0.0"
 description = "AI agent development framework embracing continuous improvement (kaizen)"
 readme = "README.md"
 license = {file = "LICENSE"}