Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
81 lines (68 loc) · 4.28 KB

CONTRIBUTING.md

File metadata and controls

81 lines (68 loc) · 4.28 KB

Contributing to Opik

Thanks for your interest in contributing to Opik.

If you are looking for setup instructions and contribution workflows, start with our docs:

You can also read and edit those docs directly in this repository:

  • apps/opik-documentation/documentation/fern/docs/contributing/overview.mdx
  • apps/opik-documentation/documentation/fern/docs/contributing/local-development.mdx

Please review the CLA before contributing:

Repository layout at a glance

  • apps/: deployable services and product surfaces (backend, frontend, docs, and supporting backends)
  • sdks/: SDKs (python, typescript, opik_optimizer) and code generation
  • tests_end_to_end/: end-to-end suites and helpers
  • deployment/: Docker and Helm deployment assets

Component-specific guides

Fast path

  1. Open or confirm a tracked issue first (Fixes #... or Resolves #...).
  2. Create a branch: {username}/{ticket}-{summary} where ticket is OPIK-####, issue-####, or NA.
  3. Keep changes scoped to the requested area.
  4. Run relevant formatters, linters, and tests before opening a PR.
  5. Open a draft PR with GitHub CLI: gh pr create --draft.
  6. Fill .github/pull_request_template.md completely.

Generated files (do not edit manually)

  • apps/opik-backend/src/main/resources/model_prices_and_context_window.json
  • apps/opik-frontend/src/data/model_prices_and_context_window.json

These files are regenerated by automation from upstream BerriAI/litellm. Use the updater workflow or approved automation, not direct edits.

Commit and PR conventions

  • First commit (used as PR title source):
    • [<TICKET-KEY>] [BE|FE|SDK|DOCS|INFRA|NA] <type>: <summary>
  • Follow-up commits:
    • <type>(<scope>): <summary> where type is one of feat, fix, refactor, test, docs, chore.
  • Include screenshots/videos for user-facing UI changes.
  • Keep customer names, non-public internal references, and sensitive operational context out of public PR text.

AI-assisted contributions

AI assistance is allowed, but human authors remain accountable for correctness, licensing, and security.

Rules:

  • Always run relevant tests/linters for touched code.
  • Always be explicit about human/users interaction with produced output.
  • Always review prior issues, pull requests, and existing code for related solutions.
  • Always address system-generated reviews (Baz, Greptile).
  • Never submit unreviewed AI output.
  • Never include secrets, tokens, private prompts, internal system instructions, or customer-sensitive data in generated/public content.
  • Never disclose vulnerabilities, exploit steps, or incident details in public issues/PRs (use private maintainer/security channels).
  • Include the PR template AI watermark/disclosure block when AI is used.

Agent/editor setup

  • Cursor compatibility: make cursor (.cursor -> .agents)
  • Codex compatibility: make codex (.codex -> .agents, generates AGENTS.override.md from .agents/rules/*.mdc)
  • Claude sync: make claude (syncs .agents to .claude)
  • Git hooks: make hooks