From 7bdde95cb4bcf8fb4528c1d47eb551fb74c89b07 Mon Sep 17 00:00:00 2001 From: Chris Farhood Date: Sun, 15 Feb 2026 08:39:17 -0500 Subject: [PATCH] docs: Add release process and changelog Add comprehensive release management documentation and changelog. New files: - .github/workflows/tag-release.md: Complete release process guide - Semantic versioning guidelines - 3 methods for creating releases (CLI, git, web UI) - Version bump guidelines (major/minor/patch) - Pre-release support (alpha/beta/rc) - Release checklist - Docker image tagging strategy - Example workflows - CHANGELOG.md: Changelog following Keep a Changelog format - Unreleased section with all current features - Template for future releases - Adheres to Semantic Versioning Release Process: 1. Create annotated git tag (e.g., v1.0.0) 2. Push tag to GitHub 3. GitHub Actions automatically: - Builds Docker image - Pushes with multiple tags (v1.0.0, 1.0, 1, latest) - Creates GitHub release with notes Ready for v1.0.0 release! Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude Co-Authored-By: Happy --- .github/workflows/tag-release.md | 259 +++++++++++++++++++++++++++++++ CHANGELOG.md | 98 ++++++++++++ 2 files changed, 357 insertions(+) create mode 100644 .github/workflows/tag-release.md create mode 100644 CHANGELOG.md diff --git a/.github/workflows/tag-release.md b/.github/workflows/tag-release.md new file mode 100644 index 0000000..66bd60a --- /dev/null +++ b/.github/workflows/tag-release.md @@ -0,0 +1,259 @@ +# Release Process + +This document describes how to create releases for this project. + +## Semantic Versioning + +We follow [Semantic Versioning 2.0.0](https://semver.org/): + +- **MAJOR** version (v2.0.0): Incompatible API/breaking changes +- **MINOR** version (v1.1.0): New features, backwards compatible +- **PATCH** version (v1.0.1): Bug fixes, backwards compatible + +## Creating a Release + +### Method 1: Using GitHub CLI (Recommended) + +```bash +# Ensure you're on main branch and up to date +git checkout main +git pull + +# Create and push a tag +VERSION="v1.0.0" # Change this +git tag -a "$VERSION" -m "Release $VERSION + +## What's New +- Feature 1 +- Feature 2 +- Bug fix 1 + +## Docker Image +\`\`\`bash +docker pull ghcr.io/cpfarhood/devcontainer:$VERSION +\`\`\` +" + +git push origin "$VERSION" + +# The GitHub Actions workflow will automatically: +# 1. Build the Docker image +# 2. Push to ghcr.io with multiple tags +# 3. Create a GitHub release with notes +``` + +### Method 2: Using Git Tags Only + +```bash +git checkout main +git pull + +# Create annotated tag +git tag -a v1.0.0 -m "Release v1.0.0" + +# Push tag +git push origin v1.0.0 +``` + +### Method 3: Using GitHub Web UI + +1. Go to https://github.com/cpfarhood/devcontainer/releases +2. Click "Draft a new release" +3. Click "Choose a tag" +4. Type the new version (e.g., `v1.0.0`) +5. Click "Create new tag on publish" +6. Fill in the release title and description +7. Click "Publish release" + +## What Happens Automatically + +When you push a version tag (`v*`), GitHub Actions will: + +1. **Build Docker image** with multiple tags: + - `ghcr.io/cpfarhood/devcontainer:v1.2.3` (exact version) + - `ghcr.io/cpfarhood/devcontainer:1.2` (minor version) + - `ghcr.io/cpfarhood/devcontainer:1` (major version) + - `ghcr.io/cpfarhood/devcontainer:latest` (if on default branch) + +2. **Create GitHub Release** with: + - Auto-generated release notes from commits + - Docker pull command in the description + +## Version Bump Guidelines + +### Patch Release (v1.0.X) +- Bug fixes +- Documentation updates +- Minor dependency updates +- No new features +- No breaking changes + +**Example:** v1.0.1 +```bash +git tag -a v1.0.1 -m "Release v1.0.1 - Bug fixes" +git push origin v1.0.1 +``` + +### Minor Release (v1.X.0) +- New features +- New optional configuration variables +- Enhancements to existing features +- Backwards compatible +- No breaking changes + +**Example:** v1.1.0 +```bash +git tag -a v1.1.0 -m "Release v1.1.0 - New Happy Coder features" +git push origin v1.1.0 +``` + +### Major Release (vX.0.0) +- Breaking changes +- Required configuration changes +- Removal of deprecated features +- Incompatible API changes + +**Example:** v2.0.0 +```bash +git tag -a v2.0.0 -m "Release v2.0.0 - Breaking: New storage architecture" +git push origin v2.0.0 +``` + +## Pre-releases + +For alpha, beta, or release candidates: + +```bash +# Alpha +git tag -a v1.1.0-alpha.1 -m "Release v1.1.0-alpha.1" +git push origin v1.1.0-alpha.1 + +# Beta +git tag -a v1.1.0-beta.1 -m "Release v1.1.0-beta.1" +git push origin v1.1.0-beta.1 + +# Release Candidate +git tag -a v1.1.0-rc.1 -m "Release v1.1.0-rc.1" +git push origin v1.1.0-rc.1 +``` + +## Release Checklist + +Before creating a release: + +- [ ] All tests pass +- [ ] Documentation is up to date +- [ ] CHANGELOG.md is updated (if you maintain one) +- [ ] Version number follows semver +- [ ] On main/master branch +- [ ] All changes are committed +- [ ] Tag message includes release notes + +## Docker Image Tags + +Each release creates multiple Docker tags for flexibility: + +| Git Tag | Docker Tags Created | +|---------|---------------------| +| v1.2.3 | `:v1.2.3`, `:1.2`, `:1`, `:latest` | +| v2.0.0 | `:v2.0.0`, `:2.0`, `:2`, `:latest` | +| v1.2.4-beta.1 | `:v1.2.4-beta.1`, `:1.2-beta` | + +**Usage examples:** +```bash +# Specific version (recommended for production) +docker pull ghcr.io/cpfarhood/devcontainer:v1.2.3 + +# Minor version (gets patches automatically) +docker pull ghcr.io/cpfarhood/devcontainer:1.2 + +# Major version (gets minor updates and patches) +docker pull ghcr.io/cpfarhood/devcontainer:1 + +# Latest (always gets newest stable release) +docker pull ghcr.io/cpfarhood/devcontainer:latest +``` + +## Viewing Releases + +- **GitHub Releases:** https://github.com/cpfarhood/devcontainer/releases +- **Docker Images:** https://github.com/cpfarhood/devcontainer/pkgs/container/devcontainer +- **Git Tags:** `git tag -l` + +## Deleting a Release + +If you need to delete a bad release: + +```bash +# Delete local tag +git tag -d v1.0.0 + +# Delete remote tag +git push origin :refs/tags/v1.0.0 + +# Delete GitHub release (use web UI or gh CLI) +gh release delete v1.0.0 +``` + +**Note:** Docker images pushed to ghcr.io cannot be easily deleted. It's better to create a new patch version. + +## First Release + +For the initial v1.0.0 release: + +```bash +git checkout main +git pull + +git tag -a v1.0.0 -m "Release v1.0.0 - Initial Release + +## Features +- Antigravity IDE with web-based VNC access +- Happy Coder AI assistant integration +- Automatic GitHub repository cloning +- Persistent home directory with ReadWriteMany PVC +- Secure non-root execution (claude user, UID 1000) +- Support for private repositories with GitHub token +- HTTPRoute (Gateway API) support +- Multi-platform Docker images +- Comprehensive deployment documentation + +## Docker Image +\`\`\`bash +docker pull ghcr.io/cpfarhood/devcontainer:v1.0.0 +\`\`\` + +## Deployment +See DEPLOYMENT.md for complete deployment instructions. +" + +git push origin v1.0.0 +``` + +## Example Release Workflow + +```bash +# 1. Finish your feature/fix on a branch +git checkout feature/new-feature +git commit -m "feat: Add new feature" +git push + +# 2. Create PR and merge to main +gh pr create +# ... get approval and merge ... + +# 3. Pull latest main +git checkout main +git pull + +# 4. Create release tag +git tag -a v1.1.0 -m "Release v1.1.0 - New feature" +git push origin v1.1.0 + +# 5. Wait for GitHub Actions +# - Check: https://github.com/cpfarhood/devcontainer/actions + +# 6. Verify release +# - GitHub: https://github.com/cpfarhood/devcontainer/releases +# - Docker: docker pull ghcr.io/cpfarhood/devcontainer:v1.1.0 +``` diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..c7da18a --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,98 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added +- Initial project setup +- Antigravity IDE (VSCode) with web-based VNC access +- Happy Coder AI assistant integration +- Automatic GitHub repository cloning on startup +- Persistent home directory with ReadWriteMany PVC support +- Secure non-root execution (claude user, UID 1000, GID 1000) +- Support for private repositories via GitHub token +- HTTPRoute (Gateway API) support +- VNC password protection +- Multi-platform Docker image builds +- GitHub Actions CI/CD pipeline +- Automated releases on version tags +- Comprehensive deployment documentation (DEPLOYMENT.md) +- Complete variables reference (VARIABLES.md) + +### Container Features +- Base: jlesage/baseimage-gui:ubuntu-22.04-v4 +- Antigravity IDE (VSCode) +- Happy Coder npm package +- Chrome browser +- Node.js (LTS) +- Python 3 +- Git + +### Kubernetes Resources +- StatefulSet with volumeClaimTemplates +- ReadWriteMany PVC for /home directory +- ConfigMap for configuration +- Sealed Secrets support +- HTTPRoute for external access +- Service (headless) + +### Configuration Options +- GitHub repository URL (required) +- GitHub token (optional, for private repos) +- VNC password (optional) +- Happy Coder server URL (optional) +- Happy Coder webapp URL (optional) +- Display resolution (configurable) +- Resource limits (configurable) +- Storage size (configurable) + +### Documentation +- README.md with quick start guide +- DEPLOYMENT.md with step-by-step instructions +- VARIABLES.md with complete variable reference +- Release process documentation +- Pull request template +- Dependabot configuration + +## Version History + +No releases yet. See [Unreleased] section above for planned v1.0.0 features. + +--- + +## Release Template + +Use this template for future releases: + +```markdown +## [1.0.0] - YYYY-MM-DD + +### Added +- New features +- New configuration options + +### Changed +- Changes to existing features +- Updated dependencies + +### Deprecated +- Features that will be removed in future versions + +### Removed +- Removed features +- Breaking changes + +### Fixed +- Bug fixes +- Security patches + +### Security +- Security improvements +- Vulnerability fixes +``` + +[Unreleased]: https://github.com/cpfarhood/devcontainer/compare/v1.0.0...HEAD