CodeVetter · Repo Unpack · Contributor handoff
d3/d3
Edit the barrel, the docs, and the release wiring. Do not vendor algorithm source into this repo. Read package.json, src/index.js, rollup.config.js, docs/.vitepress/config.ts, and the two tests before changing exports or pages. Use yarn. Build dist before any docs command. Never run the postpublish script unless a human explicitly asked to publish and push tags. The link test is strict about .md suffixes and header slugs.
- Read first: package.json (exports, files, scripts, dependency list), src/index.js, bundle.js, rollup.config.js, docs/.vitepress/config.ts, docs/.vitepress/theme/index.ts, test/d3-test.js, test/docs-test.js, prebuild.sh from line 628, and .github/workflows/test.yml plus deploy.yml. API.md and the root README are not the API.
- Safe edits are docs markdown, docs/components Vue examples, sidebar and api index entries, the barrel export list, and Rollup banner or output tweaks. Unsafe or out of scope: copying d3-selection or d3-geo implementations into src/, committing dist/ or docs/public versioned bundles, editing yarn.lock by hand, and running npm publish or the postpublish git push.
- Install and test with yarn, not a second lockfile: CI uses yarn --frozen-lockfile and setup-node cache: yarn. The local test command is yarn test, which needs the d3-* packages installed because d3-test.js dynamic-imports every dependency. Node on CI is 20 even though engines says >=12.
- Before yarn docs:dev or yarn docs:build, run yarn prepublishOnly so dist/d3.mjs exists for the Vite alias. A full asset mirror also needs a checkout of d3/d3.github.com at build/d3.github.com, which deploy.yml does and test.yml does not. prebuild.sh will not stop on the first missing historical file.
- When adding a module, update all of: package.json dependencies, src/index.js, prebuild.sh node_modules cp lines, .gitignore, a docs page, docs/api.md links, and themeConfig.sidebar. Then run yarn test. The parity test only covers the first two; the link test covers the docs links; the copy list and sidebar are unchecked.
- Anchor trap: docs-test.js requires internal links to use a .md suffix in the source even though the site uses cleanUrls. Header slugs lower-case, turn runs of spaces into single hyphens, and delete other punctuation. If a heading's slug is wrong or unstable, add an explicit {#anchor} rather than fighting the regex. Protocol links are ignored, so external URLs are not validated.
- ESLint trap: root ecmaVersion is 8, test ecmaVersion is 11 with mocha and browser env. New syntax in src/ or rollup.config.js can fail the root config even if Node 20 accepts it. The test workflow's compact formatter must keep matching .github/eslint.json or annotations break; the regex expects "path: line N, col N, Error - message (rule)".
- Version trap: the user-visible version is package.json version, inlined as __APP_VERSION__ and written into the Rollup banner. The CDN filename written by prebuild is the major line d3.v7.js, not the full 7.9.0. Bumping the minor version does not rename that file. CHANGES.md is only for major releases; patch notes belong in GitHub releases.
- Do not treat globalThis.d3 in the theme as a library API. enhanceApp sets it for console testing on the docs site only. Library consumers get the package exports or the UMD global created by the bundle's name: "d3".
- Map and plot examples depend on devDependencies topojson-client and @observablehq/plot and on network at runtime or build time. Editing WorldMap, UsMap, or PlotRender without those packages installed, or without dist/d3.mjs, will not typecheck or render. There is no browser test to catch a broken example; verify by running the docs build.
- Publishing to npm is not automated in .github/workflows. The only publish-adjacent automation is postpublish's git push and git push --tags, plus prepublishOnly's destructive rm -rf dist. Treat both as release steps that require an explicit human request. (inferred)