Skip to content

AGENTS.md

Latest commit

 

History

History
80 lines (67 loc) · 4.67 KB

AGENTS.md

File metadata and controls

80 lines (67 loc) · 4.67 KB
Raw

Contributor instructions

Commit conventions

  • Use the examples: Conventional Commit prefix for changes whose primary purpose is updating or fixing examples, including their dedicated tests. Apply the same prefix to pull request titles; do not use fix: or fix(examples): for these changes.
  • Choose Conventional Commit prefixes based on user impact. Reserve fix: for changes that materially change the shipped gem's behavior in a way that impacts users. CI-only, workflow-only, build/test infrastructure, and repository-maintenance changes should use an appropriate non-user-facing prefix such as ci:. For example, a change like PR #572 should be titled ci: restore Castiron statuses for fork PRs, not fix(ci): restore Castiron statuses for fork PRs, because it changes CI behavior rather than gem behavior.

Ruby implementation guidelines

  • Prefer direct method calls over Ruby reflection (send, __send__, or public_send) for internal SDK plumbing. When an internal method must be callable across components without becoming supported public API, keep the method public for direct dispatch and mark it @api private. Keep its RBI and RBS declarations at the same visibility.

Release maintenance

When regenerating gemfiles/bedrock.gemfile.lock, preserve the x-release-please markers around the local openai version. Release Please uses them to update this lockfile; Bundler can remove them when rewriting it.

Custom-code budget

Follow the custom-code guidance. Budget changes belong in a separate PR containing only .castiron-ratchet.json, with an explicit justification in the PR description. Increases require a human approving review before merging. Agents may investigate and draft proposals, but must not approve budget increases (including through a human's credentials) or bypass the gate. Do not weaken counting, broaden exclusions, or alter generation metadata to make a change pass. The checker and effective budget come from main, not the PR. Keep default CODEOWNERS.

Security requirements

  • Never commit real API keys, access tokens, signing keys, credentials, or customer data. Read secrets from environment variables such as OPENAI_API_KEY and use clearly fake values in examples, tests, and fixtures.
  • Redact authorization headers, cookies, tokens, signed URLs, customer data, and sensitive request/response bodies, prompts, or uploaded files from logs, errors, snapshots, and CI artifacts. Clearly fake or sanitized payloads may remain in tests and diagnostics.
  • Review direct and transitive dependency changes in Gemfile, Gemfile.lock, docs/Gemfile, docs/Gemfile.lock, and openai.gemspec, including gem sources, locked Git revisions, native extensions, and install/build scripts. Do not run unreviewed scripts.
  • Pin GitHub Actions to full commit SHAs and preserve least-privilege job permissions, permissions: {}, and persist-credentials: false.
  • Protect GitHub App private keys and release credentials. Preserve protected release environments and RubyGems trusted publishing; grant id-token: write only to the publishing job and never introduce long-lived publishing tokens.
  • Request @openai/sdks-team review for changes involving authentication, endpoints/transports, redirects, TLS, file uploads/paths, deserialization, logging, webhooks, dependencies, or CI/release behavior. Add focused regression/security tests and follow the generated-code guidance in CONTRIBUTING.md.
  • Report suspected vulnerabilities privately as described in SECURITY.md, never in public issues or pull requests.

Large-payload compatibility

Treat large payloads as a normal API contract, not evidence of malformed or hostile input. Responses, Chat Completions, and other APIs can legitimately return large application/json bodies and SSE streaming events. Do not introduce arbitrary fixed limits on HTTP bodies, events, or lines as a security or efficiency fix. Prefer incremental processing, amortized-linear buffering, timely cleanup, and caller cancellation. Any new rejection limit needs an explicit, owner-approved API contract and a review of existing supported payloads and transports.

Protect this behavior with focused, deterministic public-entrypoint tests using large synthetic payloads generated in memory, not committed captures or live image generation. Their high memory use is intentional: do not shrink the payloads or raise client limits to make the tests pass. Keep coverage to the main HTTP JSON and streaming categories, and run large cases sequentially to keep peak memory reasonable. The fixture size is a regression probe, not a new API maximum.