|
| 1 | +# Gemini Context & Memories |
| 2 | + |
| 3 | +## Project: cigen / docspring migration |
| 4 | + |
| 5 | +### Core Concepts & "The New Way" |
| 6 | + |
| 7 | +- **cigen vs. Old Config:** We are migrating DocSpring's CircleCI configuration from a Ruby-based generator (`generate_circle_ci_config.rb`) to `cigen`. The old config logic is the "source of truth" for intended behavior (job logic), but `cigen` manages the structure, caching, and hashing. |
| 8 | +- **Auto-Injection & Caching:** `cigen` automatically wraps jobs with logic to compute a `JOB_HASH` based on source files and configuration. It handles caching (`save_cache`, `restore_cache` for job status) and skipping jobs that have already passed for a given hash. |
| 9 | +- **No Manual Hashing:** We should **not** see manual `calculate_sha256_hash` or `update_cache_exists` steps in the new `cigen` YAML files for standard jobs. This logic is now handled by `cigen`'s auto-injection. |
| 10 | +- **Source File Groups:** `source_files` keys in job definitions refer to groups defined in `docspring/.cigen/config/source_file_groups.yml`. This is how `cigen` knows which files to hash for a job. |
| 11 | +- **Configuration Layering:** `cigen` config is merged from `docspring/.cigen/config.yml` and `docspring/.cigen/config/*`. |
| 12 | + |
| 13 | +### Key Corrections & Rules |
| 14 | + |
| 15 | +- **CRITICAL RULE: No Inter-Stage Job Dependencies:** Jobs within different stages **cannot** directly depend on each other. Dependencies are managed at the **stage level** (stages depend on other stages). If Job A requires Job B, they **must** be in the same stage. |
| 16 | +- **Job Naming Convention & Stages:** |
| 17 | + - **Correct Stages:** |
| 18 | + - `ci` (Linting, Testing, Docs Install/Lint/Compile) |
| 19 | + - `build` (App & Enterprise Docker Images, Manifests) |
| 20 | + - `deploy_staging` (Staging Deploy & Postman) |
| 21 | + - `deploy_docs` (Docs Deploy) |
| 22 | + - `deploy_us`, `deploy_eu`, `deploy_all` (Production Deploys) |
| 23 | + - `post_deploy` (Merge Branch) |
| 24 | + - **Noun Redundancy Convention:** If a stage name contains a noun (e.g., `deploy_docs`), the job file should describe the verb/action without repeating the noun (e.g., `deploy.yml` -> `deploy_docs_deploy`). |
| 25 | +- **`docspring/.cigen/workflows/main/jobs/deploy/`:** This folder is specifically for **multi-stage Rails app deployment jobs (staging, US, EU)** using a matrix. Docs-related deployment jobs (`deploy_docs`) do _not_ belong here. |
| 26 | +- **`cigen_shallow_checkout`**: This step is **automatically injected** by `cigen`. It should **not** be explicitly listed as a step in job definitions. |
| 27 | +- **Docs Isolation & Monorepo Optimization:** |
| 28 | + - Docs are isolated. `docs_lint` and `compile_docs` (renamed `compile`) are in the `ci` stage (for fast feedback/blocking bad merges), but `build_app_image` does **not** depend on them. |
| 29 | + - `deploy_docs` is in its own stage. |
| 30 | + |
| 31 | +### Enterprise Image Pipeline |
| 32 | + |
| 33 | +- **Multi-Arch:** We build `amd64` and `arm64` images for both App and Enterprise. |
| 34 | +- **Jobs:** |
| 35 | + - `build_app_image` (Multi-arch, in `build`) |
| 36 | + - `create_app_docker_manifest` (Requires `build_app_image`, pushes manifest) |
| 37 | + - `build_enterprise_image` (Multi-arch, in `build`, requires `build_app_image`) |
| 38 | + - `create_enterprise_docker_manifest` (Requires `build_enterprise_image`, pushes manifest) |
| 39 | +- **Ordering:** `deploy_staging` depends on `build` stage, ensuring all images and manifests are ready before deployment/merge. |
| 40 | + |
| 41 | +### Key Commands |
| 42 | + |
| 43 | +- **Build cigen:** `cargo build --release` (run in root) |
| 44 | +- **Generate config:** `cd docspring && ../target/release/cigen` |
| 45 | +- **Compare configs:** `source .venv/bin/activate && ./scripts/compare_ci_configs.py` (requires `pyyaml`) |
0 commit comments