Raxx · internal docs

internal · gated

C++ Service Onboarding Checklist

Owner: software-architect Last updated: 2026-05-29 UTC Background: docs/architecture/queue-cpp-scaffold-review-2026-05-13.md (vcpkg incident 2026-05-13) Applies to: Every new tier-1 C++ service scaffold PR (Queue Phase 2, Velvet rewrite, MQ-A rewrite, and any future service)

Purpose

On 2026-05-13 UTC, three sequential vcpkg bugs surfaced during the Queue staging deploy because queue/vcpkg.json was authored without running vcpkg install against its pinned baseline. Each bug required a 20-minute Docker build to discover. This checklist prevents that pattern from recurring on the next C++ service.

The checklist is not optional. card-groomer verifies it is present and complete in the PR description before accepting a scaffold card.

Before opening a PR

Before opening any PR that touches queue/Dockerfile, queue/vcpkg.json, or queue/CMakeLists.txt, run bin/queue-local-build from repo root. A green build is required — the script exits non-zero on any vcpkg, cmake, or compile failure, giving you the exact error before the 20-minute staging deploy cycle.

Pre-PR Checklist

Complete every item before opening the scaffold PR. Paste the checklist into your PR description with checkboxes checked.

[ ] vcpkg.json uses exact `version` constraints for all dependencies (not `version>=`)
    — See [ADR-0085](https://internal-docs.raxx.app/architecture/adr/0085-flag-reconciler-bidirectional-sync.html).

[ ] builtin-baseline SHA is documented in queue/vcpkg-notes.md with the date it was
    chosen (UTC).

[ ] vcpkg install ran clean in a fresh container at the pinned baseline.
    Use the exact command:

    docker run --rm -v $(pwd)/<service-dir>:/src gcc:13-bookworm bash -c "
      apt-get update -qq && apt-get install -y -qq cmake ninja-build git curl zip unzip pkg-config ca-certificates &&
      git clone https://github.com/microsoft/vcpkg.git /opt/vcpkg &&
      /opt/vcpkg/bootstrap-vcpkg.sh -disableMetrics &&
      /opt/vcpkg/vcpkg install --triplet x64-linux --x-manifest-root=/src/
    "

    Replace <service-dir> with your service directory.
    Exit code must be 0. State the date of the run in the PR description.

[ ] All packages verified: no "version not in database" errors, no "feature not found"
    errors from the vcpkg install run above.

[ ] Dockerfile uses full git clone (no --depth 1) for vcpkg.
    Shallow clones cannot resolve a pinned builtin-baseline SHA.
    See: docs/ops/incidents/2026-05-27-queue-deploy-vcpkg-shallow-clone.md

[ ] vcpkg-notes.md added alongside vcpkg.json. Contents:
    - builtin-baseline SHA
    - Date of last clean vcpkg install run (UTC)
    - For each direct dependency: one sentence on why it was chosen, which features
      are enabled, and any features that were explicitly excluded and why.

[ ] CI vcpkg-manifest-check job ([ADR-0087](https://internal-docs.raxx.app/architecture/adr/0087-vcpkg-manifest-ci-guard.html)) is wired for the new service's
    vcpkg.json and Dockerfile paths. If it is not yet wired, file a Card B
    sub-card before the scaffold PR merges.

[ ] AddressSanitizer (-fsanitize=address) and UBSan (-fsanitize=undefined)
    enabled in the CMake debug/CI build configuration.

[ ] No raw new/delete anywhere in the codebase. All resources RAII-managed.
    Smart pointers (unique_ptr, shared_ptr) for heap allocation.

[ ] No raw char* for any string that carries PII or a credential. Use std::string.
    No strcpy, sprintf, or gets.

[ ] Secrets read from Infisical at process startup. No secrets in CMakeLists.txt,
    Dockerfile ARGs, or any committed file. check_no_credential_fields.sh covers
    the new service directory.

Pin Policy

Use exact version (e.g., "version": "7.9.2") for all dependencies. Not version>=. See ADR-0085.

The exact version to pin is the one vcpkg install resolves when you run the verification command above. Record it.

Baseline-Update Cadence

Trigger Action
New package needed that doesn't exist at current baseline Bump baseline to a SHA where it exists. Re-run full vcpkg install. Update all exact version constraints to match. Standalone PR.
Security advisory requires dep upgrade Emergency baseline bump. Same procedure.
Quarterly cadence (planned) Bump to recent baseline. Re-verify. No urgency unless security-triggered.

Baseline bumps are always standalone PRs. Never combine a baseline bump with feature work.

Lockfile Policy

Do not commit vcpkg-lock.json. See ADR-0086 (docs/architecture/adr/0086-vcpkg-lockfile-policy.md).

Decision is Path B (Decline), closed 2026-05-29 UTC. Exact-version pinning + CI dry-run gate provides equivalent reproducibility. The lockfile format is not stable across vcpkg tool versions; adopting it would require pinning the vcpkg tool version alongside, adding maintenance cost with no marginal safety benefit at the current 9-package dep set.

Additional gotchas

References