diff --git a/docs/release-engineering.md b/docs/release-engineering.md index 6919b11..48806f5 100644 --- a/docs/release-engineering.md +++ b/docs/release-engineering.md @@ -1,3 +1,5 @@ + + # Release Engineering Documentation ## Overview @@ -70,38 +72,38 @@ All commits must follow the [Conventional Commits](https://www.conventionalcommi #### Commit Types -| Type | Description | Version Bump | Example | -|------|-------------|--------------|---------| -| `feat` | New feature | Minor (1.0.0 → 1.1.0) | `feat(admin): add password protection` | -| `fix` | Bug fix | Patch (1.0.0 → 1.0.1) | `fix(skills): prevent focus loss` | -| `perf` | Performance improvement | Patch | `perf(ui): lazy load images` | -| `feat!` | Breaking change | Major (1.0.0 → 2.0.0) | `feat(api)!: remove deprecated endpoints` | -| `docs` | Documentation only | None | `docs(readme): update installation` | -| `style` | Code style (formatting) | None | `style(ui): fix indentation` | -| `refactor` | Code refactoring | None | `refactor(auth): simplify token validation` | -| `test` | Adding/updating tests | None | `test(api): add auth middleware tests` | -| `build` | Build system changes | None | `build(docker): update node version` | -| `ci` | CI/CD changes | None | `ci(github): add staging workflow` | -| `chore` | Maintenance tasks | None | `chore(deps): update dependencies` | -| `revert` | Revert previous commit | Patch | `revert: remove broken feature` | +| Type | Description | Version Bump | Example | +| ---------- | ----------------------- | --------------------- | ------------------------------------------- | +| `feat` | New feature | Minor (1.0.0 → 1.1.0) | `feat(admin): add password protection` | +| `fix` | Bug fix | Patch (1.0.0 → 1.0.1) | `fix(skills): prevent focus loss` | +| `perf` | Performance improvement | Patch | `perf(ui): lazy load images` | +| `feat!` | Breaking change | Major (1.0.0 → 2.0.0) | `feat(api)!: remove deprecated endpoints` | +| `docs` | Documentation only | None | `docs(readme): update installation` | +| `style` | Code style (formatting) | None | `style(ui): fix indentation` | +| `refactor` | Code refactoring | None | `refactor(auth): simplify token validation` | +| `test` | Adding/updating tests | None | `test(api): add auth middleware tests` | +| `build` | Build system changes | None | `build(docker): update node version` | +| `ci` | CI/CD changes | None | `ci(github): add staging workflow` | +| `chore` | Maintenance tasks | None | `chore(deps): update dependencies` | +| `revert` | Revert previous commit | Patch | `revert: remove broken feature` | #### Allowed Scopes -| Scope | Description | -|-------|-------------| -| `admin` | Admin panel components | -| `api` | Backend API | -| `ui` | Frontend UI components | -| `docker` | Docker configuration | -| `ci` | CI/CD workflows | -| `deps` | Dependencies | -| `release` | Release configuration | -| `auth` | Authentication | -| `skills` | Skills section | -| `experience` | Experience section | -| `education` | Education section | -| `projects` | Projects section | -| `personal` | Personal info section | +| Scope | Description | +| ------------ | ---------------------- | +| `admin` | Admin panel components | +| `api` | Backend API | +| `ui` | Frontend UI components | +| `docker` | Docker configuration | +| `ci` | CI/CD workflows | +| `deps` | Dependencies | +| `release` | Release configuration | +| `auth` | Authentication | +| `skills` | Skills section | +| `experience` | Experience section | +| `education` | Education section | +| `projects` | Projects section | +| `personal` | Personal info section | ### 2. semantic-release @@ -139,6 +141,7 @@ Enforces conventional commits via: - **CI job**: Validates commits in pull requests Configuration in `commitlint.config.js`: + - Validates commit types - Validates scopes - Enforces lowercase subjects @@ -146,10 +149,10 @@ Configuration in `commitlint.config.js`: ### 4. Husky Git Hooks -| Hook | Purpose | Command | -|------|---------|---------| -| `pre-commit` | Run linting before commit | `npm run lint` | -| `commit-msg` | Validate commit message | `commitlint --edit` | +| Hook | Purpose | Command | +| ------------ | ------------------------- | ------------------- | +| `pre-commit` | Run linting before commit | `npm run lint` | +| `commit-msg` | Validate commit message | `commitlint --edit` | ### 5. GitHub Actions Workflows @@ -250,16 +253,16 @@ Runs on: Schedule (daily at 02:00 UTC) ## Docker Image Tags -| Tag | Registry | Description | Update Frequency | -|-----|----------|-------------|------------------| -| `latest` | Both | Latest stable release | Every release | -| `v1.0.0` | Both | Specific version | Immutable | -| `1.0` | Both | Major.minor | Points to latest patch | -| `1` | Both | Major version | Points to latest minor | -| `staging` | Both | Staging environment | Every staging push | -| `nightly` | Both | Latest nightly build | Daily | -| `edge` | Both | Alias for nightly | Daily | -| `2026-02-20` | Both | Date-specific nightly | Immutable | +| Tag | Registry | Description | Update Frequency | +| ------------ | -------- | --------------------- | ---------------------- | +| `latest` | Both | Latest stable release | Every release | +| `v1.0.0` | Both | Specific version | Immutable | +| `1.0` | Both | Major.minor | Points to latest patch | +| `1` | Both | Major version | Points to latest minor | +| `staging` | Both | Staging environment | Every staging push | +| `nightly` | Both | Latest nightly build | Daily | +| `edge` | Both | Alias for nightly | Daily | +| `2026-02-20` | Both | Date-specific nightly | Immutable | ### Pulling Images @@ -277,11 +280,11 @@ docker pull ghcr.io/owner/cv-app:v1.0.0 ## Environments -| Environment | Branch | Trigger | Docker Tag | -|-------------|--------|---------|------------| -| Production | `master` | semantic-release (feat/fix commits) | `latest`, `vX.Y.Z` | -| Staging | `staging` | Push to branch | `staging` | -| Nightly | `master` | Daily at 02:00 UTC | `nightly`, `edge`, `YYYY-MM-DD` | +| Environment | Branch | Trigger | Docker Tag | +| ----------- | --------- | ----------------------------------- | ------------------------------- | +| Production | `master` | semantic-release (feat/fix commits) | `latest`, `vX.Y.Z` | +| Staging | `staging` | Push to branch | `staging` | +| Nightly | `master` | Daily at 02:00 UTC | `nightly`, `edge`, `YYYY-MM-DD` | ## Release Flow Example @@ -379,11 +382,11 @@ Developer commits: feat(admin): add export functionality Configure these in GitHub repository settings → Secrets and variables → Actions: -| Secret | Description | Required For | -|--------|-------------|--------------| -| `DOCKERHUB_USERNAME` | Docker Hub username | Docker Hub push | -| `DOCKERHUB_TOKEN` | Docker Hub access token | Docker Hub push | -| `GITHUB_TOKEN` | GitHub token (automatic) | GHCR push, releases | +| Secret | Description | Required For | +| -------------------- | ------------------------ | ------------------- | +| `DOCKERHUB_USERNAME` | Docker Hub username | Docker Hub push | +| `DOCKERHUB_TOKEN` | Docker Hub access token | Docker Hub push | +| `GITHUB_TOKEN` | GitHub token (automatic) | GHCR push, releases | ### Creating Docker Hub Token @@ -427,6 +430,7 @@ git commit -m "docs: update readme [skip ci]" **Error**: `subject must be lower-case` **Fix**: Use lowercase for the subject: + ```bash # Wrong git commit -m "feat(ui): Add new button" @@ -438,6 +442,7 @@ git commit -m "feat(ui): add new button" ### Release Not Triggering **Causes**: + 1. No release-worthy commits (only docs/style/refactor/test/build/ci/chore) 2. Commit message contains `[skip ci]` 3. Workflow already running @@ -449,6 +454,7 @@ git commit -m "feat(ui): add new button" **Error**: `denied: requested access to the resource is denied` **Fix**: + 1. Verify `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` secrets 2. Ensure Docker Hub token has Write permission 3. Check Docker Hub repository exists (or enable auto-create) @@ -458,21 +464,22 @@ git commit -m "feat(ui): add new button" **Cause**: semantic-release requires conventional commits with proper types. **Fix**: Ensure commits follow: + - `feat:` for features (minor bump) - `fix:` for bug fixes (patch bump) - `feat!:` or `BREAKING CHANGE:` for breaking changes (major bump) ## File Reference -| File | Purpose | -|------|---------| -| `.releaserc.json` | semantic-release configuration | -| `commitlint.config.js` | Commitlint rules | -| `.husky/pre-commit` | Pre-commit hook (lint) | -| `.husky/commit-msg` | Commit message hook (commitlint) | -| `.github/workflows/ci.yml` | CI pipeline | -| `.github/workflows/release.yml` | Release pipeline | -| `.github/workflows/staging.yml` | Staging deployment | -| `.github/workflows/nightly.yml` | Nightly builds | -| `docker-bake.hcl` | Multi-platform Docker build config | -| `CHANGELOG.md` | Auto-generated changelog | +| File | Purpose | +| ------------------------------- | ---------------------------------- | +| `.releaserc.json` | semantic-release configuration | +| `commitlint.config.js` | Commitlint rules | +| `.husky/pre-commit` | Pre-commit hook (lint) | +| `.husky/commit-msg` | Commit message hook (commitlint) | +| `.github/workflows/ci.yml` | CI pipeline | +| `.github/workflows/release.yml` | Release pipeline | +| `.github/workflows/staging.yml` | Staging deployment | +| `.github/workflows/nightly.yml` | Nightly builds | +| `docker-bake.hcl` | Multi-platform Docker build config | +| `CHANGELOG.md` | Auto-generated changelog |