Release Process¶

This guide covers the complete release process for the Code Graph Knowledge System, including version management, Docker builds, and deployment.

Overview¶

Release Types¶

Major Release (x.0.0) - Breaking changes, major new features
Minor Release (0.x.0) - New features, backward compatible
Patch Release (0.0.x) - Bug fixes, minor improvements
Hotfix Release (0.0.x) - Critical bug fixes

Release Artifacts¶

Each release produces: - Git tag (vX.Y.Z) - GitHub release with release notes - Docker images (minimal, standard, full) - PyPI package (future) - Updated documentation

Release Schedule¶

Major releases: As needed (quarterly target)
Minor releases: Monthly
Patch releases: As needed
Hotfixes: Immediate (for critical issues)

Version Strategy¶

Semantic Versioning¶

We follow Semantic Versioning 2.0.0:

MAJOR.MINOR.PATCH
  |     |     |
  |     |     +-- Bug fixes, minor improvements
  |     +-------- New features, backward compatible
  +-------------- Breaking changes, major features

Version Examples¶

Patch Release (0.6.1 → 0.6.2): - Fix Neo4j connection timeout - Update dependency versions - Fix documentation typos

Minor Release (0.6.2 → 0.7.0): - Add automatic memory extraction - New MCP tools - Performance improvements

Major Release (0.7.0 → 1.0.0): - Complete API redesign - New authentication system - Breaking configuration changes

Current Version¶

Version is managed in: - pyproject.toml: version = "0.3.0" - Git tags: v0.7.0 - Docker images: royisme/codebase-rag:0.7.0-*

Pre-Release Checklist¶

Before starting a release, ensure:

Code Quality¶

All tests pass locally
CI/CD pipeline is green
Code coverage meets requirements (70%+)
No known critical bugs
Security scan passes (Trivy)
Code review completed for all changes

Documentation¶

Dependencies¶

Dependencies up to date
Security vulnerabilities addressed
Compatibility tested
Requirements files updated

Testing¶

# Run full test suite
pytest tests/ -v --cov=services --cov=api --cov=mcp_tools

# Run integration tests
pytest tests/ -m integration

# Test Docker builds locally
docker build -f docker/Dockerfile.minimal -t test:minimal .
docker build -f docker/Dockerfile.standard -t test:standard .
docker build -f docker/Dockerfile.full -t test:full .

Communication¶

Release notes drafted
Breaking changes communicated
Known issues documented
User announcements prepared

Release Process¶

Step 1: Prepare Release Branch¶

# Ensure main branch is up to date
git checkout main
git pull origin main

# Create release branch
git checkout -b release/v0.7.0

Step 2: Update Version Numbers¶

Update version in pyproject.toml:

[project]
name = "code-graph"
version = "0.7.0"  # Update this
description = "Add your description here"

Optional: Update version in other files if needed:

# If version is defined elsewhere
find . -name "*.py" -exec grep -l "__version__" {} \;

Step 3: Update CHANGELOG.md¶

# Changelog

## [0.7.0] - 2025-01-15

### Added
- Automatic memory extraction from conversations
- Git commit analysis for memory extraction
- Code comment mining for TODO/FIXME markers
- Query-based memory suggestions
- Batch repository extraction

### Changed
- Improved MCP handler architecture
- Enhanced error messages for memory operations

### Fixed
- Neo4j connection timeout in Docker
- Memory search relevance scoring

### Security
- Updated dependencies with security patches

## [0.6.0] - 2024-12-20
...

Step 4: Update Documentation¶

# Update user documentation
vim docs/guide/memory-extraction.md

# Update API documentation
vim docs/api/memory-endpoints.md

# Update README if needed
vim README.md

Step 5: Commit Changes¶

# Commit version and changelog updates
git add pyproject.toml docs/changelog.md README.md
git commit -m "chore: prepare release v0.7.0"

# Push release branch
git push origin release/v0.7.0

Step 6: Create Pull Request¶

Create PR from release/v0.7.0 to main
Title: "Release v0.7.0"
Description: Include release notes
Request review from maintainers
Wait for CI/CD to pass
Merge when approved

Step 7: Tag the Release¶

# After PR is merged, checkout main
git checkout main
git pull origin main

# Create annotated tag
git tag -a v0.7.0 -m "Release version 0.7.0

### Added
- Automatic memory extraction features
- Enhanced MCP tools

### Changed
- Improved error handling

### Fixed
- Neo4j connection issues"

# Push tag to trigger release workflow
git push origin v0.7.0

Step 8: Monitor Automated Builds¶

The tag push triggers GitHub Actions workflows:

Docker builds (docker-build.yml)
Builds minimal, standard, and full images
Tags with version number and latest
Pushes to Docker Hub
GitHub release (docker-build.yml)
Creates GitHub release
Generates release notes
Attaches artifacts

Monitor at: https://github.com/royisme/codebase-rag/actions

Docker Image Builds¶

Build Configuration¶

Three Docker images are built for each release:

1. Minimal Image¶

Tag: royisme/codebase-rag:0.7.0-minimal Contents: Code Graph only, no memory features Size: ~800MB Use case: Lightweight code analysis

# docker/Dockerfile.minimal
FROM python:3.13-slim
# ... minimal dependencies

2. Standard Image¶

Tag: royisme/codebase-rag:0.7.0-standard Contents: Code Graph + Memory Store Size: ~1.2GB Use case: Memory-enhanced development

# docker/Dockerfile.standard
FROM python:3.13-slim
# ... includes memory features

3. Full Image¶

Tag: royisme/codebase-rag:0.7.0-full (also latest) Contents: All features + UI + monitoring Size: ~1.5GB Use case: Complete development environment

# docker/Dockerfile.full
FROM python:3.13-slim
# ... all features included

Automated Build Process¶

When a version tag is pushed:

GitHub Actions triggered by tag push
Build images for all three variants
Multi-platform build (amd64, arm64)
Push to Docker Hub with multiple tags:
Version tag: 0.7.0-minimal
Major.minor tag: 0.7-minimal
Variant tag: minimal
Latest tag: latest (full image only)

Manual Docker Build¶

For testing or emergency releases:

# Build minimal
docker build -f docker/Dockerfile.minimal -t royisme/codebase-rag:0.7.0-minimal .

# Build standard
docker build -f docker/Dockerfile.standard -t royisme/codebase-rag:0.7.0-standard .

# Build full
docker build -f docker/Dockerfile.full -t royisme/codebase-rag:0.7.0-full .

# Test image
docker run -d --name test-release \
  -p 8000:8000 \
  -e NEO4J_URI=bolt://neo4j:7687 \
  royisme/codebase-rag:0.7.0-full

# Verify
curl http://localhost:8000/api/v1/health

# Cleanup
docker stop test-release
docker rm test-release

# Push manually (if needed)
docker push royisme/codebase-rag:0.7.0-minimal
docker push royisme/codebase-rag:0.7.0-standard
docker push royisme/codebase-rag:0.7.0-full

Docker Image Testing¶

# Test minimal image
docker-compose -f docker/docker-compose.minimal.yml up -d
# Run smoke tests
curl http://localhost:8000/api/v1/health
docker-compose -f docker/docker-compose.minimal.yml down

# Test standard image
docker-compose -f docker/docker-compose.standard.yml up -d
# Test memory endpoints
curl -X POST http://localhost:8000/api/v1/memory/add -H "Content-Type: application/json" -d '{"project_id":"test","memory_type":"decision","title":"Test","content":"Test"}'
docker-compose -f docker/docker-compose.standard.yml down

# Test full image
docker-compose -f docker/docker-compose.full.yml up -d
# Access monitoring UI
open http://localhost:8000/ui/monitor
docker-compose -f docker/docker-compose.full.yml down

GitHub Release¶

Automated Release Creation¶

The docker-build.yml workflow automatically creates a GitHub release when a tag is pushed:

- name: Create Release
  uses: softprops/action-gh-release@v1
  with:
    generate_release_notes: true
    body: |
      ## Docker Images

      ### Minimal (Code Graph only)
      ```bash
      docker pull royisme/codebase-rag:0.7.0-minimal
      ```

      ### Standard (Code Graph + Memory)
      ```bash
      docker pull royisme/codebase-rag:0.7.0-standard
      ```

      ### Full (All Features)
      ```bash
      docker pull royisme/codebase-rag:0.7.0-full
      ```

Manual Release Creation¶

If automated release fails:

Go to: https://github.com/royisme/codebase-rag/releases/new
Tag: Select v0.7.0
Title: "Release v0.7.0 - Automatic Memory Extraction"
Description: Copy from CHANGELOG.md and add Docker pull commands
Attachments: Add any additional files
Click "Publish release"

Release Notes Template¶

## What's New in v0.7.0

This release introduces automatic memory extraction capabilities, enabling the system to learn from conversations, code comments, and git commits.

### 🚀 New Features

- **Automatic Memory Extraction**: Extract memories from AI conversations
- **Git Commit Analysis**: Analyze commits for decisions and experiences
- **Code Comment Mining**: Extract TODO, FIXME, NOTE markers
- **Batch Repository Extraction**: Comprehensive codebase analysis
- **5 new MCP tools** for memory extraction

### 🔧 Improvements

- Enhanced error messages for memory operations
- Improved MCP handler architecture (78% code reduction)
- Better timeout handling for large documents

### 🐛 Bug Fixes

- Fixed Neo4j connection timeout in Docker environments
- Resolved memory search relevance scoring issues
- Fixed environment variable handling in Docker

### 📚 Documentation

- Complete memory extraction guide
- Updated API documentation
- New troubleshooting guide

### 🐳 Docker Images

#### Minimal (Code Graph only)
```bash
docker pull royisme/codebase-rag:0.7.0-minimal

Standard (Code Graph + Memory)¶

docker pull royisme/codebase-rag:0.7.0-standard

Full (All Features)¶

docker pull royisme/codebase-rag:0.7.0-full
docker pull royisme/codebase-rag:latest

📖 Documentation¶

Full documentation: https://code-graph.vantagecraft.dev

⚠️ Breaking Changes¶

None in this release.

🙏 Contributors¶

Thanks to all contributors who made this release possible!

Full Changelog: https://github.com/royisme/codebase-rag/compare/v0.6.0...v0.7.0

## Documentation Updates

### Update Documentation Site

```bash
# Update MkDocs documentation
cd docs/

# Build documentation locally
mkdocs build

# Test locally
mkdocs serve
# Open http://localhost:8000

# Documentation auto-deploys via GitHub Actions
# Verify at: https://code-graph.vantagecraft.dev

Update Docker Hub¶

Go to: https://hub.docker.com/r/royisme/codebase-rag
Update description with latest version info
Update README with new features
Add release notes

Update README Badges¶

Update version badges in README.md:

[![Version](https://img.shields.io/badge/version-0.7.0-blue.svg)](https://github.com/royisme/codebase-rag/releases/tag/v0.7.0)
[![Docker](https://img.shields.io/docker/v/royisme/codebase-rag?label=docker)](https://hub.docker.com/r/royisme/codebase-rag)

Post-Release Tasks¶

Immediate Tasks (Within 24 Hours)¶

Monitor Docker Hub for successful image pushes
Test deployed images with quick smoke tests
Check documentation site updated correctly
Monitor error reports from new release
Respond to GitHub issues related to release

Week 1 Tasks¶

Monitor metrics for performance regressions
Track user feedback on new features
Address critical bugs with hotfix if needed
Update project board with next milestone
Write blog post announcing release (optional)

Ongoing Tasks¶

Close resolved issues that were fixed in release
Update roadmap with completed features
Plan next release with new features
Review and merge pending PRs
Engage with community feedback

Hotfix Process¶

For critical bugs that need immediate release:

Step 1: Create Hotfix Branch¶

# Branch from latest release tag
git checkout v0.7.0
git checkout -b hotfix/v0.7.1

Step 2: Fix the Bug¶

# Make minimal changes to fix critical bug
vim services/memory_store.py

# Add tests
vim tests/test_memory_store.py

# Commit fix
git add .
git commit -m "fix: resolve critical memory corruption issue"

Step 3: Update Version¶

# Update to patch version
vim pyproject.toml  # 0.7.0 → 0.7.1

# Update changelog
vim docs/changelog.md

Step 4: Fast-Track Release¶

# Push hotfix branch
git push origin hotfix/v0.7.1

# Create PR to main (expedited review)
# After merge, tag immediately
git checkout main
git pull origin main
git tag -a v0.7.1 -m "Hotfix: Critical memory corruption"
git push origin v0.7.1

Step 5: Communicate¶

Post GitHub release immediately
Notify users in discussions
Update documentation
Consider backporting to older versions if needed

Rollback Procedures¶

If a release has critical issues:

Docker Rollback¶

Users can revert to previous version:

# Pull previous version
docker pull royisme/codebase-rag:0.6.0-full

# Update docker-compose.yml
image: royisme/codebase-rag:0.6.0-full

# Restart
docker-compose down
docker-compose up -d

Git Rollback¶

For repository issues:

# Revert to previous release
git checkout v0.6.0

# Or create revert commit
git revert <commit-hash>
git push origin main

Communication¶

Create GitHub issue explaining the problem
Update release notes with warning
Publish hotfix as soon as possible
Document root cause and prevention measures

Release Checklist Summary¶

## Pre-Release
- [ ] All tests passing
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] Version bumped in pyproject.toml
- [ ] Dependencies updated
- [ ] Security scan passed

## Release
- [ ] Create release branch
- [ ] Update version numbers
- [ ] Commit and push changes
- [ ] Create and merge PR
- [ ] Create and push git tag
- [ ] Monitor Docker builds
- [ ] Verify GitHub release created

## Post-Release
- [ ] Test Docker images
- [ ] Verify documentation updated
- [ ] Announce release
- [ ] Monitor for issues
- [ ] Close related issues
- [ ] Plan next release

Questions?¶

For questions about the release process:

Check Contributing Guide
Review previous releases
Ask in GitHub Discussions
Contact maintainers

Useful Commands Reference¶

# Version bump helper
grep -r "version" pyproject.toml

# List all tags
git tag -l

# Show tag details
git show v0.7.0

# Delete local tag
git tag -d v0.7.0

# Delete remote tag (careful!)
git push origin :refs/tags/v0.7.0

# Compare releases
git log v0.6.0..v0.7.0 --oneline

# Build all Docker images
for variant in minimal standard full; do
  docker build -f docker/Dockerfile.$variant -t royisme/codebase-rag:0.7.0-$variant .
done

Release Process¶

Overview¶

Release Types¶

Release Artifacts¶

Release Schedule¶

Version Strategy¶

Semantic Versioning¶

Version Examples¶

Current Version¶

Pre-Release Checklist¶

Code Quality¶

Documentation¶

Dependencies¶

Testing¶

Communication¶

Release Process¶

Step 1: Prepare Release Branch¶

Step 2: Update Version Numbers¶

Step 3: Update CHANGELOG.md¶

Step 4: Update Documentation¶

Step 5: Commit Changes¶

Step 6: Create Pull Request¶

Step 7: Tag the Release¶

Step 8: Monitor Automated Builds¶

Docker Image Builds¶

Build Configuration¶

1. Minimal Image¶

2. Standard Image¶

3. Full Image¶

Automated Build Process¶

Manual Docker Build¶

Docker Image Testing¶

GitHub Release¶

Automated Release Creation¶

Manual Release Creation¶

Release Notes Template¶

Standard (Code Graph + Memory)¶

Full (All Features)¶

📖 Documentation¶

⚠️ Breaking Changes¶

🙏 Contributors¶

Update Docker Hub¶

Update README Badges¶

Post-Release Tasks¶

Immediate Tasks (Within 24 Hours)¶

Week 1 Tasks¶

Ongoing Tasks¶

Hotfix Process¶

Step 1: Create Hotfix Branch¶

Step 2: Fix the Bug¶

Step 3: Update Version¶

Step 4: Fast-Track Release¶

Step 5: Communicate¶

Rollback Procedures¶

Docker Rollback¶

Git Rollback¶

Communication¶

Release Checklist Summary¶

Questions?¶

Useful Commands Reference¶

Resources¶