From 30daabf12c82d64faf1efa8b6cfeb9423eab2f32 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 19 Oct 2025 13:42:32 +0200 Subject: [PATCH] Add release management system and prepare v1.0.0 publication MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- Makefile | 198 ++++++++++++++++++++++++++++++++- README.md | 13 ++- agents/agent-releaseManager.md | 101 +++++++++++++++++ docs/GETTING_STARTED.md | 22 +++- pyproject.toml | 2 +- 5 files changed, 331 insertions(+), 5 deletions(-) create mode 100644 agents/agent-releaseManager.md diff --git a/Makefile b/Makefile index ec71452..0f25161 100644 --- a/Makefile +++ b/Makefile @@ -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" \ No newline at end of file + @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 "; \ + echo " โ€ข Delete tags: git tag -d v"; \ + 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" \ No newline at end of file diff --git a/README.md b/README.md index a0b6a08..566eb49 100644 --- 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) diff --git a/agents/agent-releaseManager.md b/agents/agent-releaseManager.md new file mode 100644 index 0000000..6a4831f --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index 3998cf0..49323dc 100644 --- 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 diff --git a/pyproject.toml b/pyproject.toml index 108974c..fd33d35 100644 --- 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"}