From 97798df41748fe9acc7c1d7a807887d0bdb0e276 Mon Sep 17 00:00:00 2001 From: ruberoid Date: Fri, 17 Oct 2025 12:44:23 +0400 Subject: [PATCH] docs: Add detailed CI/CD workflow examples to CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add 'How to trigger' sections with exact git commands for each pipeline - Include practical examples: feature testing, contract publishing, releases - Add 'Common CI/CD Workflows' section with real-world scenarios - Document emergency rollback procedure - Clarify contract-only service names (telegram_listener vs telegram-listener) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CLAUDE.md | 159 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 139 insertions(+), 20 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e8d4d0d..82379c8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -179,39 +179,158 @@ This eliminates NuGet warning NU1507 and ensures consistent package resolution a The project uses Drone CI with 5 specialized pipelines: ### 1. Feature Validation (`feature/*`, `fix/*` branches) -- Triggered on push to feature/fix branches +**Purpose**: Test feature branches before merging to main + +**How to trigger**: +```bash +# Create feature branch and push +git checkout -b feature/my-new-feature +# ... make changes ... +git add . +git commit -m "Add new feature" +git push origin feature/my-new-feature +``` + +**What happens**: - Runs build + tests with Testcontainers support - Provides fast feedback before merge - Duration: ~3-5 minutes ### 2. Main Validation (`main` branch) -- Triggered on push to main +**Purpose**: Ensure main branch stays healthy after merge + +**How to trigger**: +```bash +# Merge feature to main +git checkout main +git merge feature/my-new-feature +git push origin main +``` + +**What happens**: - Same checks as feature validation -- Ensures main branch stays healthy +- Ensures main branch builds and tests pass - Duration: ~3-5 minutes -### 3. Contracts-Only Publish (tags with `contracts_only:`) -- Triggered by tag + commit message containing `contracts_only:` -- Publishes NuGet contracts without building Docker images -- Fast iteration on contract changes +### 3. Contracts-Only Publish +**Purpose**: Publish NuGet contracts without building Docker images (fast iteration) + +**How to trigger**: +```bash +# Update contracts in a submodule +cd telegram-listener +# ... update Async.Api.Contracts ... +git add . && git commit -m "Add MessageEdited event" +git push + +# From parent repo, tag with contracts_only marker +cd .. +git add telegram-listener +git commit -m "contracts_only:telegram_listener - Add MessageEdited event" +git tag 0.7.41 +git push && git push --tags +``` + +**What happens**: +- Publishes only the specified service's NuGet contracts +- Skips Docker image builds - Duration: ~2 minutes -- Example: `git commit -m "contracts_only:telegram_listener - Add MessageEdited event"` -### 4. Full Release (clean tags) -- Triggered by tag without special markers -- Complete release cycle: - 1. Publish all NuGet contracts (parallel) - 2. Build all Docker images with Kaniko (parallel, after contracts) - 3. Deploy to Kubernetes (automatic for `v*` tags) +**Services**: `telegram_listener`, `text_matcher`, `users` + +### 4. Full Release +**Purpose**: Complete release - contracts + images + deployment + +**How to trigger**: +```bash +# Make your changes, commit to main +git add . +git commit -m "Implement new feature" +git push + +# Tag for full release (no special markers in commit message) +git tag v1.3.0 +git push --tags +``` + +**What happens**: +1. Publishes all NuGet contracts (parallel) +2. Builds all Docker images with Kaniko (parallel, after contracts) +3. Deploys to Kubernetes (automatic for `v*` tags) - Duration: ~8-10 minutes -- Example: `git tag v1.3.0` -### 5. Deploy-Only (tags with `deploy_only:`) -- Triggered by tag + commit message containing `deploy_only:` -- Skips building, only deploys existing images -- Useful for rollbacks and hotfixes +### 5. Deploy-Only +**Purpose**: Deploy existing images without rebuilding (rollbacks, hotfixes) + +**How to trigger**: +```bash +# Deploy already-built images (e.g., rollback to previous version) +git commit --allow-empty -m "deploy_only: Rollback to v1.2.9" +git tag deploy-v1.2.9 +git push && git push --tags + +# Or deploy latest images +git commit --allow-empty -m "deploy_only: Deploy latest" +git tag deploy-latest +git push && git push --tags +``` + +**What happens**: +- Skips building entirely +- Deploys specified tag's images (or `latest`) - Duration: ~1 minute -- Example: `git commit --allow-empty -m "deploy_only: Deploy v1.2.9"` + +## Common CI/CD Workflows + +### Test a Feature Branch +```bash +git checkout -b feature/add-logging +# ... make changes ... +git add . && git commit -m "Add structured logging" +git push origin feature/add-logging +# ✅ Drone runs feature-validation pipeline +``` + +### Publish Contracts After API Changes +```bash +cd text-matcher +# Update Nocr.TextMatcher.Async.Api.Contracts +git add . && git commit -m "Add UserDeleted event" +git push + +cd .. +git add text-matcher +git commit -m "contracts_only:text_matcher - Add UserDeleted event" +git tag 0.8.5 +git push && git push --tags +# ✅ Drone publishes text-matcher contracts to NuGet +``` + +### Full Release Workflow +```bash +# Work on main branch +git add . +git commit -m "Implement payment processing" +git push +# ✅ Drone runs main-validation + +# Tag for release +git tag v2.0.0 +git push --tags +# ✅ Drone runs full-release pipeline: +# 1. Publishes all contracts +# 2. Builds all Docker images +# 3. Deploys to Kubernetes +``` + +### Emergency Rollback +```bash +# Rollback to last known good version +git commit --allow-empty -m "deploy_only: Emergency rollback to v1.9.5" +git tag rollback-v1.9.5 +git push && git push --tags +# ✅ Drone deploys v1.9.5 images immediately (~1 minute) +``` ### Deployment Scripts