docs: add contributor-workflow.md, track an AGENTS.md pointing at it - #802
docs: add contributor-workflow.md, track an AGENTS.md pointing at it#802mparrett wants to merge 4 commits into
Conversation
|
@nooga Thoughts on restoring CLAUDE.md in the repo? |
Honestly I forgot about those files a while ago. What's the reasoning behind bringing it back? |
The hypothesis is restoring the conventional AGENTS/CLAUDE indices would improve quality / reduce defects on contributor PRs. Not strictly necessary but recommended by Anthropic, and I suspect most new contributors would be using Claude code. I have a custom workspace with many supports, and rarely initiate development on a clean checkout, so any gap here would be masked for my own work. It's a small sample size but we do see some defects in contributor PRs. I don't have a super strong opinion here, but think it's would be a small net help with little downsides. Little risk of going stale if you keep them lean and pointed to the right dev docs and scripts. I wasn't sure if maybe the previous preference to exclude it was based on anti-AI sentiment, but that would be understandable. |
|
@mparrett that makes sense, green light from me! |
|
@nnunley thoughts? This wouldn't replace any of the hooks or other agentic tooling/workflow stuff we've discussed. |
One page for the mechanics between a clone and a green PR: the make targets and go test invocations CI actually runs, the generated-artifact rule, where tests and docs go, the two native registration paths and three compile paths, and a table of every job in go.yml with what it guards and its local equivalent. Existing docs own the detail; this page points at them. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
AGENTS.md points at docs/ instead of restating it: the one rule people trip on (regenerate after .lg edits), where tests and docs go, the two native registration paths and three compile paths, and upstream etiquette. CLAUDE.md is the one-line @AGENTS.md import so Claude Code loads the same file; other agents read AGENTS.md directly. Both were gitignored since 2026-05; this un-ignores them. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…diff is a differential run pkg/rt/core_go_lowered/ is a build artifact (.gitignore: its self-lower is wall-clock-nondeterministic), not a committed generated file, and the gogen-diff job runs TestGogenAOTDiff over test/gold-aot fixtures rather than comparing lowering output against a committed tree. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…_*.lg and //lg:native markers generated.manifest lists the IR tables and the annotated primitives as inputs alongside pkg/rt/core; a doc that names only the core sources sends an IR-table edit past the rule it exists to state. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
f029be0 to
f52ed4e
Compare
2 participants
Why
The mechanics between a clone and a green PR are spread across the Makefile,
go.yml,.pre-commit-config.yaml, and five docs. A contributor, or a coding agent, working on the implementation has to reassemble them each time. The rule most often missed, regenerate after editingpkg/rt/core/**/*.lg, surfaces only after an edit has silently done nothing. This PR adds one page that maps them and proposes tracking a shortAGENTS.mdthat points at it.This is a draft because tracking
AGENTS.mdreverses a deliberate choice.CLAUDE.mdwas gitignored on 2026-03-28 (cb5e4fc4),AGENTS.mdon 2026-04-30 (37a135d2), and the 113-lineCLAUDE.mdthat was still tracked came out on 2026-05-07 (9b1d56bd). The case for revisiting it: the file is 36 lines of pointers intodocs/, not a second copy of the README; the repo already tracks agent material in.agents/skills/; and an untracked file goes stale unseen, since the copy I had locally still said CI could not detect a stalecore_compiled.lgb.AGENTS.mdis the name most coding agents read, so it holds the text, andCLAUDE.mdis a one-line import of it so Claude Code reads the same text without a second copy. If the answer is still no, the docs page stands on its own and I will drop the second commit.What changed
docs/contributor-workflow.md: the make targets andgo testinvocations CI runs, the generated-artifact rule, which files it commits and thatpkg/rt/core_go_lowered/is a gitignored build artifact, with a pointer toregenerating-generated-artifacts.md, where tests and docs go, the two native registration paths (ns.Definlang.goand//lg:nativevialgprimgen) and the three compile paths (direct,*ir-compile*,-tags gogen_ir), and a table of every job ingo.ymlwith what it guards and its local equivalent. Added to the README topical map.AGENTS.md: the pointer file described above.CLAUDE.mdis the one-line@AGENTS.mdimport. The two.gitignorelines are removed.Effect on existing clones
A checkout that has an untracked
AGENTS.mdorCLAUDE.mdwill have its nextgit pullrefused withuntracked working tree files would be overwritten by merge. Move or delete the local copy first; nothing else changes.Verification
Every command and claim was checked against
mainat638b4a6a: the Makefile targets, the thirteen jobs ingo.ymland their steps,.gitignorefor the lowered tree,TestGogenAOTDiffintest/e2e/for whatgogen-diffruns,scripts/check_test_location.py, the constructors inpkg/vm/native_func.go,TestGeneratedArtifactsAreFreshinpkg/genmanifest, andshadowed_registration_test.go.python3 scripts/docs_frontmatter_hook.py --checkpasses on the new page and the README;scripts/docs_status.pyreports nothing new.