docs: add release engineering design document

docs/plans/2026-02-20-release-engineering-design.md

@@ -0,0 +1,382 @@
+# Release Engineering Design
+
+**Date:** 2026-02-20
+**Status:** Approved
+**Author:** Claude (AI Assistant)
+
+## Overview
+
+Implement a comprehensive release engineering pipeline for the CV application using semantic-release with Docker multi-registry publishing, automated changelog generation, and multi-environment deployment (production, staging, nightly).
+
+## Requirements
+
+- **Versioning:** Semantic Versioning with Conventional Commits
+- **Changelog:** Automated from conventional commit messages
+- **Release Trigger:** Continuous Delivery (automatic from main branch)
+- **Deployment Targets:** Docker Hub + GitHub Container Registry (GHCR)
+- **Environments:** Production, Staging, Nightly/Edge
+
+## Architecture
+
+```
+                    ┌─────────────────────────────────────────────────────────┐
+                    │                     GitHub Repository                     │
+                    │                                                           │
+┌──────────┐        │  main ─────────────────────────────────────────────────► │ Production Release
+│ Developer│───────►│   │                                                       │   ├─ Git tag v1.0.0
+└──────────┘        │   └─────► semantic-release                                │   ├─ GitHub Release
+                    │              ├─ version bump                               │   ├─ Docker Hub: latest, v1.0.0
+                    │              ├─ CHANGELOG.md                              │   └─ GHCR: latest, v1.0.0
+                    │              ├─ git tag                                    │
+                    │              └─ GitHub release                             │
+                    │                                                           │
+                    │  staging ───────► Deploy to staging environment           │ Staging Deployment
+                    │                    (Docker tag: staging)                   │
+                    │                                                           │
+                    │  nightly ────────► Build nightly from main                │ Nightly/Edge Builds
+                    │   (cron job)          (Docker tag: nightly, edge)         │
+                    │                                                           │
+                    └─────────────────────────────────────────────────────────┘
+```
+
+## Versioning Strategy
+
+### Semantic Versioning (SemVer)
+
+Version format: `MAJOR.MINOR.PATCH` (e.g., `1.2.3`)
+
+| Commit Type | Version Bump | Example |
+|-------------|--------------|---------|
+| `feat:` | Minor | 1.0.0 → 1.1.0 |
+| `fix:` | Patch | 1.0.0 → 1.0.1 |
+| `feat!:` or `BREAKING CHANGE:` | Major | 1.0.0 → 2.0.0 |
+| `chore:`, `docs:`, `test:`, `style:`, `refactor:`, `perf:` | None | No release |
+
+### Conventional Commits Format
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Examples:
+- `feat(admin): add password protection for admin panel`
+- `fix(skills): prevent focus loss when editing category headers`
+- `docs(readme): update installation instructions`
+- `feat(api)!: remove deprecated endpoints`
+
+### Commit Types
+
+| Type | Description | Release? |
+|------|-------------|----------|
+| `feat` | New feature | Yes (minor) |
+| `fix` | Bug fix | Yes (patch) |
+| `docs` | Documentation changes | No |
+| `style` | Code style changes (formatting) | No |
+| `refactor` | Code refactoring | No |
+| `perf` | Performance improvements | No |
+| `test` | Adding/updating tests | No |
+| `build` | Build system changes | No |
+| `ci` | CI/CD changes | No |
+| `chore` | Maintenance tasks | No |
+| `revert` | Revert previous commit | Yes (if reverted commit was releasing) |
+
+## Release Pipeline
+
+### Production Release (main branch)
+
+1. Developer pushes/merges to `main`
+2. CI workflow runs (lint, test, build, e2e, integration)
+3. semantic-release analyzes commits since last release
+4. If release-worthy commits found:
+   - Calculates new version
+   - Updates `package.json` version
+   - Generates/updates `CHANGELOG.md`
+   - Creates git tag (e.g., `v1.0.0`)
+   - Creates GitHub release with release notes
+   - Builds Docker image
+   - Pushes to Docker Hub and GHCR with version tags
+
+### Staging Deployment
+
+1. Push to `staging` branch
+2. CI workflow runs (lint, test, build)
+3. Build Docker image
+4. Push to registries with `staging` tag
+5. Deploy to staging environment
+
+### Nightly Builds
+
+1. Scheduled workflow runs at 02:00 UTC daily
+2. Checkout `main` branch
+3. Build Docker image
+4. Push to registries with tags:
+   - `nightly`
+   - `edge`
+   - `YYYY-MM-DD` (e.g., `2026-02-20`)
+
+## Docker Registry Publishing
+
+### Registry Configuration
+
+**Docker Hub:**
+- Image: `DOCKERHUB_USERNAME/cv-app`
+- Requires: `DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN` secrets
+
+**GitHub Container Registry (GHCR):**
+- Image: `ghcr.io/GITHUB_OWNER/cv-app`
+- Requires: `GITHUB_TOKEN` (automatic)
+
+### Tag Strategy
+
+| Event | Docker Hub Tags | GHCR Tags |
+|-------|-----------------|-----------|
+| Production release v1.2.3 | `latest`, `v1.2.3`, `1.2`, `1` | `latest`, `v1.2.3`, `1.2`, `1` |
+| Staging push | `staging` | `staging` |
+| Nightly build | `nightly`, `edge`, `2026-02-20` | `nightly`, `edge`, `2026-02-20` |
+
+### Multi-architecture Support
+
+Build for multiple platforms:
+- `linux/amd64` (x86_64)
+- `linux/arm64` (Apple Silicon, AWS Graviton)
+
+## Changelog Generation
+
+### Format
+
+```markdown
+## [1.1.0] - 2026-02-20
+
+### Features
+* **admin:** add password protection for admin panel (#123) ([abc1234](https://github.com/owner/repo/commit/abc1234))
+* **api:** add authentication endpoints (#120) ([def5678](https://github.com/owner/repo/commit/def5678))
+
+### Bug Fixes
+* **skills:** prevent focus loss when editing category headers (#124) ([ghi9012](https://github.com/owner/repo/commit/ghi9012))
+
+### Documentation
+* update installation instructions (#125) ([jkl3456](https://github.com/owner/repo/commit/jkl3456))
+
+### BREAKING CHANGES
+* **api:** remove deprecated `/api/v1/*` endpoints
+
+---
+
+## [1.0.0] - 2026-02-15
+...
+```
+
+### Tools
+
+- `@semantic-release/changelog` - Generates CHANGELOG.md
+- `@semantic-release/git` - Commits updated files back to repo
+- `conventional-changelog-conventionalcommits` - Preset for conventional commits
+
+## GitHub Environments
+
+### Production
+
+- **Protection:** Required reviewers (1+)
+- **Deploy Trigger:** semantic-release on main branch merge
+- **Secrets:** `DOCKERHUB_TOKEN`, `DOCKERHUB_USERNAME`
+- **URL:** Production deployment URL
+
+### Staging
+
+- **Protection:** Optional reviewers
+- **Deploy Trigger:** Push to `staging` branch
+- **URL:** Staging deployment URL
+
+### Nightly
+
+- **Protection:** None
+- **Deploy Trigger:** Scheduled (cron: `0 2 * * *`)
+- **URL:** Nightly build URL
+
+## Branch Protection Rules
+
+### main branch
+
+| Rule | Setting |
+|------|---------|
+| Require PR reviews | 1+ |
+| Dismiss stale reviews | Yes |
+| Require linear history | Yes |
+| Restrict force pushes | Yes |
+| Allow deletions | No |
+| Required status checks | `frontend`, `backend`, `integration`, `e2e` |
+
+### staging branch
+
+| Rule | Setting |
+|------|---------|
+| Require PR reviews | No |
+| Require linear history | No |
+| Restrict force pushes | No |
+| Required status checks | `frontend`, `backend` |
+
+## File Structure
+
+```
+.github/
+├── workflows/
+│   ├── ci.yml                    # Enhanced with commitlint
+│   ├── release.yml               # semantic-release workflow
+│   ├── staging.yml               # Staging deployment
+│   └── nightly.yml               # Nightly builds
+├── commitlint.config.js          # Conventional commits config
+└── .releaserc.json               # semantic-release config
+
+scripts/
+├── docker-tags.sh                # Docker tag computation
+└── release-notes.sh              # Custom release notes
+
+docker/
+├── Dockerfile                    # Multi-stage build
+└── docker-compose.prod.yml       # Production compose file
+
+CHANGELOG.md                      # Generated by semantic-release
+package.json                      # Version updated by semantic-release
+```
+
+## Implementation Components
+
+### 1. semantic-release Configuration
+
+`.releaserc.json`:
+```json
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    "@semantic-release/npm",
+    "@semantic-release/git",
+    "@semantic-release/github"
+  ]
+}
+```
+
+### 2. commitlint Configuration
+
+`commitlint.config.js`:
+```javascript
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'type-enum': [2, 'always', [
+      'feat', 'fix', 'docs', 'style', 'refactor',
+      'perf', 'test', 'build', 'ci', 'chore', 'revert'
+    ]],
+    'scope-enum': [2, 'always', [
+      'admin', 'api', 'ui', 'docker', 'ci', 'deps'
+    ]]
+  }
+};
+```
+
+### 3. Husky Git Hooks
+
+```bash
+npx husky init
+echo "npx commitlint --edit \$1" > .husky/commit-msg
+```
+
+### 4. GitHub Workflows
+
+**release.yml:**
+- Triggers on push to main
+- Runs semantic-release
+- Builds and pushes Docker images
+
+**staging.yml:**
+- Triggers on push to staging branch
+- Builds and pushes Docker images with staging tag
+
+**nightly.yml:**
+- Triggers on schedule (daily at 02:00 UTC)
+- Builds from main with nightly/edge tags
+
+### 5. Docker Configuration
+
+Multi-stage Dockerfile with:
+- Build stage for frontend
+- Build stage for backend
+- Production stage with nginx
+
+Multi-platform build using `docker buildx`
+
+## Security Considerations
+
+1. **Secrets Management:**
+   - Use GitHub Secrets for sensitive values
+   - Never commit secrets to repository
+   - Use `GITHUB_TOKEN` for GHCR (automatic)
+
+2. **Branch Protection:**
+   - Require PR reviews for main
+   - Require status checks to pass
+   - Restrict force pushes
+
+3. **Docker Image Security:**
+   - Use minimal base images (alpine)
+   - Run as non-root user
+   - Scan images for vulnerabilities (optional: Trivy)
+
+4. **Environment Protection:**
+   - Required reviewers for production
+   - Environment-specific secrets
+
+## Migration Plan
+
+1. **Phase 1: Setup Tooling**
+   - Install semantic-release and plugins
+   - Configure commitlint and husky
+   - Create .releaserc.json
+
+2. **Phase 2: Update Workflows**
+   - Enhance ci.yml with commitlint
+   - Create release.yml
+   - Create staging.yml
+   - Create nightly.yml
+
+3. **Phase 3: Docker Publishing**
+   - Configure Docker Hub credentials
+   - Update Dockerfile for multi-platform
+   - Test image publishing
+
+4. **Phase 4: Branch Protection**
+   - Create staging branch
+   - Configure branch protection rules
+   - Create GitHub environments
+
+5. **Phase 5: First Release**
+   - Make a conventional commit
+   - Verify semantic-release runs
+   - Check GitHub release created
+   - Verify Docker images published
+
+## Success Criteria
+
+- [ ] Conventional commits enforced via commitlint
+- [ ] Version automatically bumped based on commit types
+- [ ] CHANGELOG.md automatically generated and updated
+- [ ] Git tags created for each release
+- [ ] GitHub releases created with release notes
+- [ ] Docker images published to Docker Hub and GHCR
+- [ ] Multi-platform Docker images (amd64, arm64)
+- [ ] Staging deployments on staging branch push
+- [ ] Nightly builds running daily
+- [ ] Branch protection rules enforced
+
+## References
+
+- [semantic-release Documentation](https://semantic-release.gitbook.io/)
+- [Conventional Commits Specification](https://www.conventionalcommits.org/)
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [Docker Multi-platform Builds](https://docs.docker.com/build/building/multi-platform/)