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 <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
This commit is contained in:
@@ -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
|
||||||
|
```
|
||||||
@@ -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
|
||||||
Reference in New Issue
Block a user