# Repository Guidance

## Generated SDK

Most SDK source is generated by Stainless. Follow `CONTRIBUTING.md` before
changing generated files. Handwritten policy, automation, tests, and examples
should remain small and should not alter exported SDK APIs unless the change
explicitly requires it.

## Go version policy

- `go.mod` is the authoritative technical minimum Go version.
- `GO_VERSION_POLICY.md` is the human-readable support and release policy.
- The supported release lines are the current and immediately preceding stable
  Go releases. A grace period explicitly documented in
  `GO_VERSION_POLICY.md` adds the retired minimum as a third line. CI tests the
  latest patch release in every supported line.
- Keep the `go` directives in the root, `examples`,
  `internal/testdata/consumer`, and `tools` modules aligned.
- Do not combine a minimum-Go-version change with unrelated SDK or Azure
  dependency upgrades.

## Changing the minimum Go version

When changing a `go` directive:

1. Update all four modules and run `go mod tidy` in each module.
2. Update `README.md`, `CONTRIBUTING.md`, and `GO_VERSION_POLICY.md`.
3. Update the minimum/current CI matrix in `.github/workflows/ci.yml`.
4. Add a `## Release note` section to the pull request description that names
   the new minimum and the final SDK release compatible with retired Go
   versions. Do not promise security backports for an old SDK release.
5. Obtain SDK CODEOWNER approval.

The stable `Go support policy` check aggregates the deterministic Go safety
jobs and is a required status check on `main`. It proves the proposed repository
state builds and tests correctly; it does not attempt to interpret release
policy or pull request prose.

## Automation map

- `.github/workflows/ci.yml`
  - On branch pushes: lint, tidy, and tests on each supported Go line.
  - On pull requests: the same lint and test coverage, plus reachable
    vulnerability checks.
  - Nightly: reachable-vulnerability checks only, so newly published
    advisories are detected even when the repository has not changed.
- `.github/workflows/go-version-review.yml`
  - Monthly and manually: gives Codex a snapshot of the official Go release
    feed and asks it to reconcile the modules, CI, and documentation.
  - Uses `OPENAI_API_KEY` from the `ci` Actions environment. That environment
    permits only the `main` branch, so a dispatch against another ref cannot
    receive the secret.
  - Runs a pinned Codex runtime as the normal GitHub-hosted runner user after
    `codex-action` irreversibly removes that user's sudo access. The built-in
    `:workspace` permission profile limits writes to the disposable checkout
    and system temporary directories and denies command network access.
  - Before exposing the API key, the workflow disables Go's per-user config and
    automatic toolchain selection, creates ignored workspace-local Go cache and
    temporary directories before `setup-go` probes the Go environment, and
    warms every module's dependencies. `setup-go` caching is disabled in this
    job so those model-writable directories are never persisted or restored
    across the publisher boundary. This avoids cross-user HOME, XDG, and cache
    ownership setup while keeping model-run Go commands inside the sandbox's
    writable workspace.
  - Codex can prepare a patch but has read-only GitHub permissions and no
    repository credential. A separate job with no OpenAI credential opens one
    draft pull request from that patch. If a generated draft is already open,
    automation leaves it untouched for maintainers.
  - The publisher independently rejects changes outside the documented policy
    files. Because generated-branch CI is dispatched, it accepts only quoted
    Go-version literal changes in `ci.yml`; changes to workflow permissions,
    triggers, actions, jobs, or steps are rejected before push.
  - After validating that allowlist, the publisher runs the complete tidy,
    build, test, and vulnerability suite without an OpenAI or GitHub credential.
    Only a later step receives the short-lived GitHub token used to push the
    validated branch and open its draft pull request.
  - The publisher can write repository contents and pull requests but cannot
    dispatch Actions. A third job can dispatch Actions but cannot write
    repository contents or pull requests.
  - Because GitHub suppresses normal workflow events for pull requests created
    with `GITHUB_TOKEN`, the publishing job explicitly dispatches CI,
    compatibility detection, and CodeQL on the generated branch.
  - The draft never merges automatically. Normal CI and CODEOWNER review remain
    authoritative.
- `.github/dependabot.yml`
  - Weekly: proposes coordinated Go dependency updates for the coupled root,
    examples, and external-consumer modules. The isolated tools module and
    pinned GitHub Actions receive independently reviewable updates.
  - Never auto-merges dependency or Go-version changes.

## Validation

Before publishing a Go-version or dependency change, run:

```sh
go mod tidy -diff
(cd examples && go mod tidy -diff)
(cd internal/testdata/consumer && go mod tidy -diff)
(cd tools && go mod tidy -diff)
go test ./...
(cd examples && go test ./...)
(cd internal/testdata/consumer && go test -mod=readonly ./...)
(cd tools && go install golang.org/x/vuln/cmd/govulncheck)
govulncheck ./...
(cd examples && govulncheck ./...)
```

Also test with `GOTOOLCHAIN=local` on every Go release line listed in the CI
matrix. Use `scripts/detect-breaking-changes` when a dependency update could
affect exported APIs.
