evlog Contributing Guide

Contributing to evlog

The repository's own AGENTS.md is the source of truth for all of this. It changes; this skill does not restate it in full on purpose. Read AGENTS.md from the repo before giving specifics.

Your system context has a Workspace section saying whether the repository is checked out on this turn. With a checkout, read_file /workspace/AGENTS.md: free, and at the ref you were summoned on. Without one, github__getFileContent on AGENTS.md at the root of the repository that section names.

What follows is the shape of the answer, so you know what to look for and what to warn about.

The parts people get wrong

• A changeset is required for anything a consumer of evlog would notice: a feature, a bug fix, a breaking change. pnpm changeset, committed alongside the code. Changes confined to apps/* or examples/* never need one. A PR without a changeset for a user-facing change does not merge.
• Conventional Commits, lowercase subject. feat: add stream server, not feat: Add stream server. Omit the scope when the change is cross-cutting; never use evlog as a scope. A new subsystem needs its scope registered in both .github/workflows/semantic-pull-request.yml and .github/pull_request_template.md, and because title validation reads the base branch, that registration has to land in an earlier PR.
• The scope list is a closed set, and you read it before you write the title. .github/workflows/semantic-pull-request.yml holds the only scopes CI accepts. Anything else fails Validate PR title, and a scope that merely sounds plausible (evlog, the package name, the app directory) is the usual way that happens. A change confined to apps/docs is docs:, with no scope: docs is already the type.
• A bug fix needs a failing regression test first, then the fix.
• New exports go in packages/evlog/package.json (exports and typesVersions) and tsdown.config.ts.
• Skills must stay in sync. If a change touches something a skill documents, the SKILL.md changes in the same PR, both the internal .agents/skills/ and the published skills/.

The Definition of Done

AGENTS.md lists eight conditions. The ones worth repeating up front: pnpm run lint, pnpm run typecheck and pnpm run test all exit 0; the change has a matching test; new public APIs have JSDoc.

Authored procedures in the repo

For anything substantial, the repo already has a step-by-step skill. Read the relevant one with github__getFileContent rather than improvising:

Each covers source, build config, package exports, tests, and every doc page that has to move with it. They are long and specific; point people at them and read the relevant section rather than summarizing from memory. On a GitHub turn they are on disk under /workspace/.agents/skills/.

Verifying a change before you propose it

The sandbox carries a ready-to-work checkout at /workspace/repo, with dependencies installed and dev:prepare already run; each session starts on the current main. When you have written or edited code, run the checks there rather than asserting they pass:

cd /workspace/repo
pnpm run lint
pnpm run typecheck
pnpm --filter evlog exec vitest run test/path/to/file

If you could not run the checks, say so plainly in the pull request body instead of implying a green build.

For authored or changed prose, run the content review even when the scanner scores 100. Capture each page with content_snapshot and send its identity to content_review, along with sources and executed-check results. Source edits must be committed before this handoff; page text can remain uncommitted. The reviewer shares the parent workspace and must use content_load. Do not edit files or change Git state while reviewers are reading. Wait for all readers to finish, recapture and compare the current identity with the rewrite input, then apply reviewed changes serially with the parent’s existing editing tools. A changed identity requires a fresh review first. Capture and review the saved file again after editing; a proposed rewrite is not verification of the saved result. A critical factual error or missing evidence blocks readiness. Follow content-pass for the verification procedure, while keeping the scope the maintainer requested.

Read the changed pages together before shipping. Each should answer a distinct reader question, agree on behavior and link to shared explanations instead of repeating them. Record the revision, command and observed result for runtime claims. After changing relevant code or examples, rerun the affected checks.