| name | contributing |
| description | How to contribute to evlog, covering commit and PR conventions, changesets, the Definition of Done, testing rules, and the authored skills that walk through building a new adapter, enricher, framework integration, or map rule. Load this for any question about contributing, opening a PR, or adding something to the package. |
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 HugoRCD/evlog.
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:
| Task | Skill |
|---|
| New drain adapter | .agents/skills/create-adapter/SKILL.md |
| New enricher | .agents/skills/create-enricher/SKILL.md |
| New framework integration | .agents/skills/create-framework-integration/SKILL.md |
New evlog map rule or framework adapter | .agents/skills/create-map-rule/SKILL.md |
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.
Shipping a change
The whole flow runs in /workspace/repo; nothing ships through the GitHub file API.
- Branch off the current
main the session starts on: git checkout -b <branch>.
- Edit, then run the checks above. A bug fix commits its failing regression test first, then the fix. For a visual change, start the dev server in the background before the checks (see
before-after, step 0) so it warms while they run. Before the first check of the session, call turbo__enable_remote_cache once, then prefix each check with TURBO_REMOTE_CACHE_READ_ONLY=true: turbo reuses the artifacts CI already built, and the template cache covers the rest, so only what the diff affects actually runs.
- When a consumer of evlog would notice the change, add a changeset: write
.changeset/<some-name>.md by hand with the --- frontmatter naming the package and bump plus a consumer-facing description (pnpm changeset is interactive and cannot run here). Look at an existing file in .changeset/ for the exact shape.
- Commit with a Conventional Commits subject: lowercase, a registered scope or none.
- Push the branch with
git__push. That tool is the only way code reaches the remote: never the GitHub file API. It refuses main and master, and only maintainer sessions have it.
- Open the pull request with
github__createPullRequest, report each check result in the body, and request hugorcd via github__requestReviewers unless it is a draft.
- Read CI back once it has run.
Validate PR title settles in seconds and is the check your own title most often breaks. A pull request announced as ready while a required check is red costs the maintainer the review; fix the title or the code and say so, rather than leaving it for them to find.
A pull request is not finished when it is open. Before you report it, the local checks are green, CI is green, and you have looked at the rendered result of anything visual. "Lint and typecheck pass" is a claim about the build, not about whether the thing you wrote is correct or reads well.
pnpm --filter @evlog/cli exec evlog map --json --no-write scores an entry point's observability and is built for exactly this: it is the fastest way to ground a "should this be logged" answer in the tree you are working in. Run the workspace copy rather than npx @evlog/cli, which would fetch and execute whatever version the registry currently serves.
Tests
packages/evlog/test/ mirrors src/ and uses Vitest. packages/evlog/test/README.md has the file layout, the framework runtime fidelity matrix, and the helper decision table; read it before answering a testing question. Framework tests must drive the framework's real request driver (supertest, app.inject, app.handle, ...), never a hand-rolled stand-in.
Style
The repo has an explicit "no slop" section: no defensive code the surrounding file does not have, no silent fallbacks, no as any, comments only for constraints the code cannot express, no speculative options. It applies to prose too: test names, error messages, changeset descriptions, PR bodies. Factual and plain.
