docs: CCIP per-team style guides

docs/style-guides/evm.md

@@ -0,0 +1,95 @@
+# EVM changeset style guide
+
+**Owning team (tracking reference):** Simon B., Robert, Anindita Ghosh.
+
+This file is a **harness**: consistent structure and **direction** for what belongs here. **Teams own all substantive rules, examples, and updates**—replace placeholders and grow this document with durable, reviewable guidance.
+
+## Purpose
+
+Capture **EVM-specific** practices for writing and reviewing CCIP tooling changesets: selectors, contract surfaces, adapter usage, and footguns that **do not** generalize to other chain families.
+
+## How to use this guide (once populated)
+
+- **While authoring:** use the rules when touching EVM adapters, bytecode/deploy steps, or chain-specific configuration in changesets.
+- **Before review or merge:** run the checklist (when added) for EVM-facing changeset PRs.
+
+## What this guide should optimize for
+
+- Correct chain and contract identity (selectors, types, versions) in changeset inputs
+- Safe sequencing of EVM deploy/upgrade/configure steps
+- Reviewable EVM-specific error modes (reverts, gas, nonces) at the changeset boundary where relevant
+
+## Related documentation
+
+- [Platform (chain-agnostic) style guide](./platform.md) — shared changeset shape and conventions.
+- [Ops / chainlink-deployments style guide](./ops.md) — how runs and pipelines are operated.
+- [Changeset Style Guide](../../deployment/docs/style-guide.md) — existing deployment changeset reference.
+- [Maintaining the Changeset Style Guide](../../deployment/docs/style-guide-contributions.md) — how to add rules, TOC, checklist, and links when editing any changeset-related guide.
+
+## Scope: what belongs here (and what does not)
+
+| In scope (this guide) | Out of scope (use instead) |
+| ----------------------- | ---------------------------- |
+| EVM **chain selectors**, contract **types/ABIs**, and adapter-specific patterns in changesets | Generic idempotency, shared datastore rules, cross-family input shape → [platform.md](./platform.md) |
+| EVM sequencing (deploy/upgrade/configure) **as it differs** from other families | Running **chainlink-deployments** pipelines, environments, operational review → [ops.md](./ops.md) |
+| Footguns that are meaningless outside EVM (e.g. chain-ID or EVM-specific ref semantics at this layer) | Adapter implementation internals → deployment architecture / adapter docs |
+
+If a rule applies equally to non-EVM families, it belongs in **platform**, not here.
+
+## Table of contents
+
+<!-- Teams: add a generated TOC or manual list as sections grow. -->
+
+## Illustrative rule shape (replace with real team rules)
+
+The section below shows the **format** only. Delete this section when you add real content, or replace it rule-by-rule.
+
+### ExampleSectionTitleToReplace
+
+**Rule:** (One clear sentence: default behavior.)
+
+**Why it matters:** (Operational / correctness / review impact—do not repeat the rule verbatim.)
+
+```go
+// ❌ BAD: (common mistake)
+
+// ✅ BETTER: (preferred pattern)
+```
+
+**Exceptions (optional):** (When the rule does not apply.)
+
+---
+
+## Copyable rule template
+
+Use this when adding a new section:
+
+````md
+## Short, Stable Section Title
+
+**Rule:** State the default behavior in one clear sentence.
+
+**Why it matters:** Explain the correctness, safety, operability, or review impact.
+
+```go
+// ❌ BAD: show the common mistake
+
+// ✅ BETTER: show the preferred pattern
+```
+
+**Exceptions (optional):** When the rule does not apply.
+````
+
+## Direction: topics for the owning team to cover
+
+Turn these **prompts** into short rules with BAD/BETTER examples where they help. Avoid duplicating topics listed in [platform.md](./platform.md) or [ops.md](./ops.md).
+
+- **Chain selectors** and EVM identity in changeset inputs (what must be explicit vs inferred).
+- **Contract types, versions, and ABI** handling in changesets—naming and evolution patterns teams should follow.
+- **EVM adapter** usage: patterns that are review-friendly and hard to misconfigure **in EVM changesets** (not generic platform idempotency—see platform).
+- **Deploy/upgrade/configure ordering** when EVM-specific ordering differs from other families.
+- **Operational footguns at the EVM boundary** reviewers should watch for (e.g. wrong network, mismatched bytecode expectations)—staying at changeset/review level, not full chain ops (see ops for CLD runs).
+
+## Contributing and updating
+
+Teams update this guide as EVM patterns evolve. Follow the maintenance pattern in [Maintaining the Changeset Style Guide](../../deployment/docs/style-guide-contributions.md): stable headings for anchors, TOC/checklist hygiene, and links to deeper docs instead of duplicating them.

docs/style-guides/ops.md

@@ -0,0 +1,97 @@
+# Ops style guide: chainlink-deployments and deployment runs
+
+**Owning team (tracking reference):** Jasmin Bakalović, Phil Ó Condúin.
+
+This file is a **harness**: consistent structure and **direction** for what belongs here. **Teams own all substantive rules, examples, and updates**—replace placeholders and grow this document with durable, reviewable guidance.
+
+## Purpose
+
+Capture **operational** practices for running and reviewing CCIP-related work through **chainlink-deployments (CLD)** and adjacent deployment workflows: environments, pipelines, how changesets are exercised in CI/CD or release paths, and what reviewers should verify for a deployment run.
+
+## How to use this guide (once populated)
+
+- **While preparing a change:** use the rules to decide how the change should be validated through CLD (or documented exceptions).
+- **Before promoting or closing a deployment-related PR:** run the checklist (when added) for operational completeness.
+
+## What this guide should optimize for
+
+- Repeatable, reviewable deployment runs with clear ownership
+- Safe promotion between environments (where applicable)
+- Observable failures and straightforward rollback or retry semantics **at the ops layer**
+
+## Related documentation
+
+- [Platform (chain-agnostic) style guide](./platform.md) — shared changeset conventions.
+- [EVM changeset style guide](./evm.md) — EVM-specific changeset authoring.
+- [Changeset Style Guide](../../deployment/docs/style-guide.md) — existing deployment changeset reference.
+- [Maintaining the Changeset Style Guide](../../deployment/docs/style-guide-contributions.md) — how to add rules, TOC, checklist, and links when editing any changeset-related guide.
+
+## Scope: what belongs here (and what does not)
+
+| In scope (this guide) | Out of scope (use instead) |
+| ----------------------- | ---------------------------- |
+| **chainlink-deployments** workflows: pipelines, jobs, how runs are triggered and reviewed | Changeset **code structure** (idempotency, refs, shared helpers) → [platform.md](./platform.md) |
+| Environment selection, promotion, and operational checklists for deployment **runs** | EVM-specific authoring (selectors, contract typing in changesets) → [evm.md](./evm.md) |
+| Expectations for testing/validating changes through CLD vs ad-hoc paths | Low-level adapter implementation → deployment architecture docs |
+
+Authoring guidance for **what goes inside a changeset** belongs in **platform** or **evm**, not here—unless the guidance is specifically about **how that changeset is run or verified** through CLD.
+
+## Table of contents
+
+<!-- Teams: add a generated TOC or manual list as sections grow. -->
+
+## Illustrative rule shape (replace with real team rules)
+
+The section below shows the **format** only. Delete this section when you add real content, or replace it rule-by-rule.
+
+### ExampleSectionTitleToReplace
+
+**Rule:** (One clear sentence: default behavior.)
+
+**Why it matters:** (Operational / correctness / review impact—do not repeat the rule verbatim.)
+
+```go
+// ❌ BAD: (common mistake)
+
+// ✅ BETTER: (preferred pattern)
+```
+
+**Exceptions (optional):** (When the rule does not apply.)
+
+---
+
+## Copyable rule template
+
+Use this when adding a new section (adapt language if the example is not Go):
+
+````md
+## Short, Stable Section Title
+
+**Rule:** State the default behavior in one clear sentence.
+
+**Why it matters:** Explain the correctness, safety, operability, or review impact.
+
+```go
+// ❌ BAD: show the common mistake
+
+// ✅ BETTER: show the preferred pattern
+```
+
+**Exceptions (optional):** When the rule does not apply.
+````
+
+## Direction: topics for the owning team to cover
+
+Turn these **prompts** into short rules with BAD/BETTER examples where they help. Avoid duplicating topics listed in [platform.md](./platform.md) or [evm.md](./evm.md).
+
+- How **chainlink-deployments** is expected to be used for CCIP-related changes (vs ad-hoc or legacy paths).
+- **Pipeline/job** conventions: naming, required stages, and what “green” must mean before promotion.
+- **Environments:** dev/stage/prod (or your equivalents)—rules of thumb for what runs where.
+- **Review of deployment outputs:** logs, artifacts, or checkpoints reviewers should expect.
+- **Secrets and configuration** at the ops layer (without duplicating in-repo changeset defaults—point to the right separation of concerns).
+- **One-off CLD pipelines:** when they are unacceptable versus durable, tested paths (tie to org risk, without naming specific incidents unless public).
+- **Observability:** what operators need to see during/after a run to trust the deployment.
+
+## Contributing and updating
+
+Teams update this guide as CLD and release practices evolve. Follow the maintenance pattern in [Maintaining the Changeset Style Guide](../../deployment/docs/style-guide-contributions.md): stable headings for anchors, TOC/checklist hygiene, and links to runbooks or internal docs instead of pasting secrets or environment-specific values.

docs/style-guides/platform.md

@@ -0,0 +1,100 @@
+# Platform changeset style guide (chain-agnostic)
+
+**Owning team (tracking reference):** Terry Tata, Will Winder.
+
+This file is a **harness**: consistent structure and **direction** for what belongs here. **Teams own all substantive rules, examples, and updates**—replace placeholders and grow this document with durable, reviewable guidance.
+
+## Purpose
+
+Capture **cross-chain** (chain-family-agnostic) practices for writing and reviewing CCIP tooling changesets: shapes, inputs, persistence conventions, and shared abstractions that should stay consistent no matter which adapter or chain family sits underneath.
+
+## How to use this guide (once populated)
+
+- **While authoring:** use the rules to structure inputs, refs, apply behavior, and error handling before review.
+- **Before review or merge:** run the checklist (when added) against changeset PRs touching shared platform code paths.
+
+## What this guide should optimize for
+
+- Safe retries and predictable apply semantics **at the platform layer**
+- Clear, explicit configuration that reviewers can reason about without chain-specific trivia
+- Consistency with repo-wide datastore and helper conventions
+- Minimal, well-bounded abstractions shared across chain families
+
+## Related documentation
+
+- [EVM changeset style guide](./evm.md) — EVM-only changeset concerns.
+- [Ops / chainlink-deployments style guide](./ops.md) — how runs and pipelines are operated.
+- [Changeset Style Guide](../../deployment/docs/style-guide.md) — existing deployment changeset reference (tooling API patterns).
+- [Maintaining the Changeset Style Guide](../../deployment/docs/style-guide-contributions.md) — how to add rules, TOC, checklist, and links when editing any changeset-related guide.
+
+## Scope: what belongs here (and what does not)
+
+| In scope (this guide) | Out of scope (use instead) |
+| ----------------------- | ---------------------------- |
+| Idempotency, ref resolution, datastore usage, and other patterns that apply **across** chain families | EVM-specific selectors, contract typing, or adapter quirks → [evm.md](./evm.md) |
+| Naming, tagging, and structural conventions for changeset inputs that are not family-specific | How to run jobs/pipelines in **chainlink-deployments** → [ops.md](./ops.md) |
+| Shared helpers, qualifiers, and “narrowest clear abstraction” at the platform layer | Deep adapter implementation detail → deployment docs such as [Cross-Family Deployment Architecture](../../deployment/docs/architecture.md) |
+
+If guidance only makes sense on EVM, it belongs in **evm**, not here. If guidance is about **operating** a deployment (environments, pipeline, review of a run), it belongs in **ops**.
+
+## Table of contents
+
+<!-- Teams: add a generated TOC or manual list as sections grow. -->
+
+## Illustrative rule shape (replace with real team rules)
+
+The section below shows the **format** only. Delete this section when you add real content, or replace it rule-by-rule.
+
+### ExampleSectionTitleToReplace
+
+**Rule:** (One clear sentence: default behavior.)
+
+**Why it matters:** (Operational / correctness / review impact—do not repeat the rule verbatim.)
+
+```go
+// ❌ BAD: (common mistake)
+
+// ✅ BETTER: (preferred pattern)
+```
+
+**Exceptions (optional):** (When the rule does not apply.)
+
+---
+
+## Copyable rule template
+
+Use this when adding a new section:
+
+````md
+## Short, Stable Section Title
+
+**Rule:** State the default behavior in one clear sentence.
+
+**Why it matters:** Explain the correctness, safety, operability, or review impact.
+
+```go
+// ❌ BAD: show the common mistake
+
+// ✅ BETTER: show the preferred pattern
+```
+
+**Exceptions (optional):** When the rule does not apply.
+````
+
+## Direction: topics for the owning team to cover
+
+Turn these **prompts** into short rules with BAD/BETTER examples where they help. Avoid duplicating topics listed in [evm.md](./evm.md) or [ops.md](./ops.md).
+
+- Apply paths that must be **safe to retry** without double-writing or double-deploying at the platform layer.
+- **Explicit, self-documenting inputs** (field names, tags) for YAML/JSON that are not EVM-specific.
+- **Refs and lookups:** resolving `AddressRef`-style inputs before use; avoiding “existence check” helpers that encode the wrong semantics.
+- **Caching and stale reads:** when cached reads are unsafe across steps in a changeset.
+- **Datastore qualifiers and naming** shared across families.
+- **Shared helpers:** when to reuse them versus local duplication.
+- **Abstractions:** prefer the narrowest abstraction that stays clear for reviewers.
+- **Validation:** avoid redundant validation; validate at the right layer.
+- **Conflicts with local conventions:** when consistency wins over a “perfect” abstraction.
+
+## Contributing and updating
+
+Teams update this guide as patterns emerge. Follow the maintenance pattern in [Maintaining the Changeset Style Guide](../../deployment/docs/style-guide-contributions.md): keep section titles stable for anchors, update any checklist/TOC you add here, and link to architecture docs instead of copying implementation detail.