Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
335 lines (243 loc) · 16.5 KB

CONTRIBUTING.md

File metadata and controls

335 lines (243 loc) · 16.5 KB
Raw

Contributing to eve

Thanks for your interest in contributing to eve! We greatly appreciate bug reports, feature proposals, and prompts or implementation plans shared through issues.

If you are an external contributor, start with an issue rather than a pull request. See Proposing a change for what to include.

The rest of this guide covers local development and the team's implementation and pull request workflow.

Signed commits

This repository requires verified commit signatures on protected branches.

Before committing code, configure Git to sign your commits with a GitHub-verified GPG, SSH, or S/MIME key. Unsigned commits will be rejected by repository rules and need to be rewritten as signed commits before they can be merged.

If a pull request includes unsigned commits, re-sign the commits and force-push the branch. Make sure the signing key is added to your GitHub account and that your commits appear as Verified.

A Signed-off-by line in the commit message is not enough to satisfy this requirement. A verified commit signature alone does not satisfy the DCO either; commits need both.

Prerequisites

  • Node.js 24+ — see .nvmrc (nvm use or fnm use)
  • pnpm — the version pinned in package.json (corepack enable handles this automatically)

Getting started

git clone https://github.com/vercel/eve.git
cd eve
pnpm install
pnpm build

The repo is a pnpm workspace orchestrated with Turborepo:

  • packages/eve — the framework and eve CLI
  • packages/eve-catalog — internal (unpublished) integration catalog
  • apps/fixtures — shared agent fixtures used by e2e tests, TUI smoke tests, local dev, and bundle analysis
  • apps/frameworks — framework integration apps for Next.js, Nuxt, SvelteKit, and TanStack Start
  • apps/templates — source apps for generated templates
  • docs — the published documentation content
  • e2e/ — fixture-owned eve eval end-to-end tests

Development

pnpm dev

This runs the eve package build in watch mode alongside the apps/fixtures/weather-agent fixture on an OS-assigned available localhost port. The fixture prints the selected URL at startup.

Testing

pnpm test               # unit + integration
pnpm test:unit          # unit tests
pnpm test:integration   # integration tests
pnpm test:scenario      # scenario tests (Turbo builds prerequisites)
pnpm test:framework-fixtures # apps/frameworks smoke builds (Turbo builds prerequisites)
pnpm test:e2e           # fixture-owned eve eval suites
pnpm test:tui           # TUI smoke scripts (not e2e)

E2E tests are fixture-owned evals. Run them from the fixture directory:

cd e2e/fixtures/agent-basic-runtime
pnpm exec eve eval --strict

The fixture agents and judges run against real models (openai/gpt-5.5), so the environment must provide the corresponding model-provider credentials.

Vercel e2e builds that same fixture directory with VERCEL=1, deploys the fixture's prebuilt Vercel output, and runs evals against the immutable deployment URL. All fixture deployments link to the same Vercel project id; the shared project's Preview env must provide those same model-provider credentials.

Do not commit fixture trees under packages/eve/test/fixtures/ — scenario app content is defined inline as ScenarioAppDescriptor objects under packages/eve/src/internal/testing/scenario-apps/ (CI enforces this).

Testing packaged builds

pkg.eve.dev serves main and same-repository PR builds. It does not serve fork PRs or direct branch deployments. A PR package is available after its Vercel – eve-pkg deployment succeeds.

pnpm dlx https://pkg.eve.dev/pr/<pull-request-id>/eve.tgz dev

pnpm dlx may reuse a cached package for the same PR URL. To test a newer commit, use its full-SHA URL: https://pkg.eve.dev/<full-sha>/eve.tgz.

Linting and formatting

pnpm lint          # oxlint (auto-fixes)
pnpm fmt           # oxfmt (also runs on staged files via the pre-commit hook)
pnpm typecheck     # TypeScript across the workspace
pnpm check:deps    # syncpack — dependency versions must stay in sync
pnpm guard:invariants  # mechanical code-invariant lints (run in CI)
pnpm docs:check    # docs frontmatter and nav validation

All of these run in CI, so running them locally before pushing saves a round trip.

Extension distribution compatibility

eve extension build records its exact eve build version and a distribution contract generation in _manifest.json. Build against the oldest eve release your extension intends to support, then test that same distribution against newer releases. A consumer rejects distributions built by a newer eve release or against an unsupported distribution generation before executing extension code. This manifest format rejects older epoch-based distributions. Generations are independent of eve versions: a new eve major release still loads every supported generation without a rebuild, and a breaking distribution contract change requires an explicit generation change and rebuild guidance.

Review changes to extension-facing APIs and runtime behavior for backwards compatibility within a supported generation. An API change does not require an epoch bump; a TypeScript-compatible signature alone does not prove an older prebuilt distribution still runs.

Adding an integration to the registry

The registry source lives under apps/docs/registry/. Add the project-owned source file to its collection directory, such as registry/connections/linear.ts or registry/extensions/browserbase.ts. Registry item names use the singular integration kind. Register the item in apps/docs/registry.json:

{
  "name": "connection/linear",
  "type": "registry:item",
  "title": "Linear",
  "description": "Connect an eve agent to Linear.",
  "dependencies": ["@vercel/connect"],
  "files": [
    {
      "path": "registry/connections/linear.ts",
      "type": "registry:file",
      "target": "agent/connections/linear.ts"
    }
  ]
}

path points to the hand-written source file relative to apps/docs; target is where eve add writes it in the consuming agent. Declare packages with dependencies and required environment variables with envVars.

Run:

pnpm --filter eve-docs registry:check

This runs shadcn build, which reads each referenced source file and embeds it as the escaped content field in apps/docs/public/r/<kind>/<slug>.json. It also rebuilds apps/docs/public/r/registry.json, validates channel, connection, and instrumentation coverage, and typechecks the registry source files. The output under apps/docs/public/r/ is gitignored and regenerated on every docs build; only the source files under apps/docs/registry/ and apps/docs/registry.json are committed.

Extension requirements

The registry and integrations gallery list reviewed, published extensions. Open an issue and get maintainer agreement before submitting a registry addition. The package must be publicly installable from npm, work with the current released eve version, and include documentation for its configuration, authentication, and any security-sensitive behavior.

In the PR, add the package as an apps/docs dev dependency, add its package to the reviewed exceptions in pnpm-workspace.yaml, and add a mount example under apps/docs/registry/extensions/. Register that example under an extension/<slug> name, with its dependencies, title, and description, in apps/docs/registry.json.

Also add the extension identity to packages/eve-catalog/src/index.ts, its gallery presentation and setup instructions to apps/docs/lib/integrations/data.ts, and a logo in apps/docs/lib/integrations/logos.tsx. Add or update focused tests for the integration page.

Documentation

User-facing docs live in docs/ and are published with the eve npm package and rendered by the docs site in apps/docs. If your change alters public behavior, update the relevant doc in the same PR and run pnpm docs:check.

Proposing a change

External contributions should come through issues rather than unsolicited pull requests. Search the existing issues, discussions, and pull requests first so you do not duplicate active work, then use the relevant issue template.

We use our own coding agents to implement accepted proposals. This lets us control which models and skills the agents use and how changes are validated. We welcome prompts as issues. Your investigation, prompt, or implementation plan helps us understand the problem and gives our agents a concrete starting point. You do not need to write the code or open a pull request to contribute.

Describe the problem, use case, or bug reproduction. If you have a change in mind, include a prompt or short implementation plan that the team can review and run with its own agents. Useful details include:

  • Explain the desired behavior and give a concrete user story or reproduction.
  • Identify the relevant code or docs and outline the changes you recommend.
  • Note constraints, trade-offs, and any public API or dependency changes.
  • Describe how to validate the result, including relevant tests and docs updates.

Start with a short prompt or plan focused on the outcome. Once a maintainer agrees on the direction, they may ask for more detail. Prompts and plans are optional: you can report a bug or request a feature without knowing how to implement it. Share what you know, even if your proposal is incomplete.

To make a proposal easier to evaluate:

  • Do not propose broad rewrites, style-only churn, formatting-only changes, or generated-output refreshes unless a maintainer asked for them.
  • Keep each issue focused on one problem.
  • Do not propose runtime dependencies without a concrete need. Prefer eve-owned wrappers, vendored code, or generated artifacts, and remember that the eve package should keep runtime dependencies minimal.
  • Do not propose public behavior based only on a hypothetical use case. Include a concrete user story or, for bugs, a reproduction.
  • Check the issue thread before developing a prompt or plan in case someone else is already working on it. Coordinate with maintainers rather than assuming an issue is assigned to you.

Submitting a pull request

Team members and contributors explicitly invited to implement a change may open a pull request. Link the issue or discussion where the change was agreed on when one exists. Do not create an issue solely to accompany a pull request.

  1. Fork the repo and create a branch from main.

  2. Make your change, including tests and docs where relevant.

  3. Sign off every commit with git commit -s.

  4. If the change affects the published eve package, add a changeset:

    pnpm changeset

  5. Make sure pnpm lint, pnpm typecheck, and pnpm test pass.

  6. Open the PR with a short description that explains the problem, user need, or decision behind the change before describing the solution.

Releases are managed with Changesets by the maintainers.

Versioning

eve follows semantic versioning. Pick the changeset bump from the change's effect on the public API described in the stability policy:

Bump Use for
patch Bug fixes, performance improvements, and other changes that add no API.
minor New features and other backward-compatible additions to the public API.
major A breaking change to a stable public API.

Experimental and internal APIs have no compatibility promise, so changes to them never need major. When a stable API needs an incompatible replacement, add the replacement beside it, mark the old API @deprecated, and remove it in the next major release.

When .changeset/pre.json has "mode": "pre", main is in Changesets prerelease mode: each release PR publishes the next prerelease, such as 1.0.0-rc.1, versioned with the tag named in that file. Prereleases still publish to npm's latest dist-tag, so npm install eve gets the newest release candidate. Maintainers enter and leave prerelease mode with pnpm changeset pre enter <tag> and pnpm changeset pre exit. The release after exiting collects every prerelease's changesets into the stable version's notes.

Changeset summaries

Start the changeset summary with one complete sentence:

---
"eve": patch
---

Restore the connection sign-in page after an authorization error.

Thanks @octocat for reporting this in #1234.

For a PR with a changeset, start the PR title with feat:, perf:, or fix:. For documentation changes, use docs(feature): or docs(bugfix): to choose the release-note section. Use chore:, refactor:, test:, ci:, build:, or internal: for changes that should not appear in either section. Except for docs, these types also accept a scope, such as fix(eve):. A stacked PR prefix such as [1/2] is also allowed. GitHub uses the PR title as the squash-merge subject; keep the prefix in that subject, which selects the category. A major changeset always appears under Breaking Changes, whatever its prefix. Put migration details and contributor credits in following paragraphs; release notes retain them. Use Thanks @handle to credit a contributor.

Run pnpm guard:invariants to validate changeset summaries. CI also checks the actual PR title.

The release workflow classifies from the immutable commit that introduced the changeset, not the editable PR title. Unrecognized commit subjects do not block the release; review them through the compare link under the version heading. That link compares with the newest earlier version that has a tag; without one, it opens the repository history at the new tag. To generate a release locally, run pnpm version-packages with GITHUB_TOKEN or GH_TOKEN set; use this command rather than changeset version so the release sections are assembled. The date is the UTC date when the release notes are generated, which can be earlier than the publication date.

The published packages contain only their own release notes in CHANGELOG.md, with a link to the full changelog at that release's tag. Packing fails if the package version has no changelog entry. Git preview builds use the base version's notes, identify them as such, and link to the source commit when it contains that version's newest notes. Use pnpm pack in the package directory; the build stages the package without modifying the repository changelog.

Developer Certificate of Origin (DCO)

We do not require a CLA. Instead, all contributions are made under the Developer Certificate of Origin (DCO), a lightweight, one-line attestation that you have the right to submit your contribution under the project's license. There is nothing to sign and no account to create.

Every commit must include a Signed-off-by line matching the commit author's name and email:

Signed-off-by: Jane Doe <jane.doe@example.com>

Add it automatically with:

git commit -s -m "your commit message"

If you forget, amend the last commit:

git commit --amend -s --no-edit

To sign off a series of commits, rebase with --signoff:

git rebase --signoff main

The sign-off requirement applies to all contributors, including Vercel employees. A required check blocks pull requests that contain commits without a valid sign-off.

Reporting bugs and requesting features

Please use the issue templates. For security issues, do not open a public issue — follow SECURITY.md instead.

Code of conduct

This project follows the Code of Conduct. By participating, you agree to uphold it.

License

eve is licensed under the Apache License 2.0. By contributing, you agree that your contributions will be licensed under that same license (inbound = outbound).