From 599205f46ff47b7d522b65725ff684589c267925 Mon Sep 17 00:00:00 2001 From: Colby McHenry Date: Fri, 30 Oct 2026 11:35:46 -0500 Subject: [PATCH] docs: add a contributing guide and a documentation index A new contributor had nothing to start from: the README covers using CodeGraph, and the build and test rules live in AGENTS.md, written for agents. CONTRIBUTING.md now covers building from source, testing a change, preparing a pull request and what happens to it. docs/README.md indexes the guides and design notes, and the README links to both. Every relative link and heading anchor was checked against main. Reimplements PR 1931 by @mixxer. Also folds in the fork-and-upstream setup, `npm run cli`, `npm run test:watch` and the version rule from PR 306 by @marcelovani, and the commit format, the single-test command, the bug-report list and the `/add-lang` pointer from PR 665 by @ymstar. Co-Authored-By: Claude Opus 5.5 --- CONTRIBUTING.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 5 ++++ docs/README.md | 26 ++++++++++++++++++ 3 files changed, 103 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 docs/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..5f9771ef4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,72 @@ +# Contributing to CodeGraph + +Thanks for helping out. Small, focused changes are the easiest to review and land. + +**Reporting a bug?** Open an [issue](https://github.com/colbymchenry/codegraph/issues) with your CodeGraph version (`codegraph --version`), Node.js version, operating system, the steps to reproduce it, what you expected, and what happened instead. A small public repository or snippet that shows the problem helps most. + +**Asking for a feature?** Describe the use case and why what's there today doesn't cover it. + +## Build from source + +You need Git, npm, and Node.js 22.5 or later, below 25. Running from source uses Node's built-in `node:sqlite`; the published installers bundle their own Node, so this only matters here. + +```bash +# Fork the repository on GitHub, then: +git clone https://github.com//codegraph.git +cd codegraph +git remote add upstream https://github.com/colbymchenry/codegraph.git + +npm ci +npm run build +``` + +A globally installed `codegraph` doesn't run your changes, so run your build directly: + +```bash +node dist/bin/codegraph.js --help # the build as it stands +npm run cli -- status # rebuild first, then run a command +npm run dev # recompile TypeScript on every save +``` + +`npm run build` covers the CLI, the SQL schema, the parser grammars and the browser viewer. Two builds are separate: + +- `npm run build:kernel` builds the optional native extraction kernel, and needs a Rust toolchain. Tests that need the kernel are skipped without it. +- `npm run build:lib` builds the viewer's component library. + +## Test your change + +```bash +npx vitest run __tests__/extraction.test.ts # one file +npx vitest run __tests__/extraction.test.ts -t "TypeScript" # tests matching a name +npm run test:watch # rerun as you edit +npm test # everything +``` + +Run the focused tests while you work, then `npm test` before opening a pull request. Tests that run the compiled CLI use `dist/`, and the test setup rebuilds it first when it's stale. + +- **Tests live in `__tests__/`** and use real files and real SQLite databases, with no database mocking. Create temporary folders with `fs.mkdtempSync` and remove them in `afterEach`. +- **A bug fix needs a test that fails without the fix.** +- **Behavior that differs by platform** gets a gated test, such as `it.runIf(process.platform === 'win32')(...)`, and needs checking on the platforms it affects. See [cross-platform validation](AGENTS.md#cross-platform-validation). +- **New language or framework support** needs validating on real repositories. Start with the `/add-lang` skill in [`.claude/skills/add-lang/SKILL.md`](.claude/skills/add-lang/SKILL.md), then follow the [validation methodology](docs/AGENTS.md#validation-methodology-required-for-every-new-languageframework) and the [coverage playbook](docs/design/dynamic-dispatch-coverage-playbook.md). Before extending a router or web framework, read [framework coverage](docs/design/framework-coverage.md). +- **A documentation-only change** doesn't need the test suite. Check its examples and links instead. + +## Prepare a pull request + +- Branch from the latest `main`, and keep to one concern. Unrelated formatting, CI or feature work belongs in its own pull request. +- Name commits `type(scope): what now works`, such as `fix(go): a constant in a const ( … ) group keeps its own doc comment`. Types in use are `feat`, `fix`, `docs`, `test`, `perf`, `chore` and `ci`. +- In the description, explain the problem, the resulting behavior, and what you ran, including any failures and any platform you couldn't test. +- Keep existing CLI commands and the default MCP tools working, unless the pull request exists to change them and says why. +- Add a line to `CHANGELOG.md` under `## [Unreleased]`, in `### New Features` or `### Fixes`, for anything a user would notice. Write one plain sentence about what changed for them, without internal file names or benchmark numbers. Changes to the `codegraph ui` viewer, which isn't released yet, go in [`docs/viewer-launch-changelog.md`](docs/viewer-launch-changelog.md) instead. +- Don't bump the version, and change `package-lock.json` only when you add or remove a dependency. +- Use public or made-up examples. Keep local paths, private code and machine-specific settings out of fixtures. + +## What happens next + +A maintainer reads every change closely before anything lands, and may ask for changes. Keep your branch up to date by rebasing on `main`. + +A maintainer may also land your contribution as their own commit, rewritten where needed, instead of merging your branch. You're credited in the changelog either way. + +## Find your way around + +- [Documentation index](docs/README.md): guides, design notes and benchmarks. +- [AGENTS.md](AGENTS.md): the architecture and the development rules, which [CLAUDE.md](CLAUDE.md) imports for Claude Code. diff --git a/README.md b/README.md index 707329655..3f5a5a598 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,7 @@ Follow [@getcodegraph](https://x.com/getcodegraph) on X for updates. - [Supported Languages](#supported-languages) - [Measured cross-file coverage](#measured-cross-file-coverage) - [Troubleshooting](#troubleshooting) +- [Contributing](#contributing) - [License](#license) ## Get Started @@ -903,6 +904,10 @@ Framework routing is validated the same way, on a canonical app per framework: E **Very large repositories (hundreds of thousands of files), or a large `.codegraph/codegraph.db-wal` file** — The `-wal` file is SQLite's write-ahead log: writes waiting to be folded into `codegraph.db`. While a big index is being built, CodeGraph lets it grow in proportion to the index (soft threshold = the larger of 256 MB and a quarter of the index size, up to 2 GB) before folding it back, because folding too often is what made large indexes slow on ordinary disks. At rest it is trimmed to 64 MB, and a leftover from a killed session is folded and trimmed the next time the project opens — the index itself has no size limit. Two environment variables tune this: `CODEGRAPH_WAL_VALVE_MB` (the soft threshold during indexing) and `CODEGRAPH_WAL_HEAL_MB` (the resting size and the trim threshold). `CODEGRAPH_WAL_VALVE_DEBUG=1` prints every decision to stderr. +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) to build from source, test a change and prepare a pull request. The [documentation index](docs/README.md) links to the project's guides and design notes. + ## License MIT diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..f4ee493e2 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,26 @@ +# Documentation + +To install and use CodeGraph, start with the [project README](../README.md). To build it and send a change, see [Contributing](../CONTRIBUTING.md). + +## Guides + +| Topic | Where to start | +|-------|----------------| +| Architecture, build rules and platform validation | [Project guide](../AGENTS.md) | +| Distribution and release packaging | [Bundling](../BUNDLING.md) | +| What telemetry collects, and how to turn it off | [Telemetry](../TELEMETRY.md) | +| Release history | [Changelog](../CHANGELOG.md) | +| Entries held for the viewer's launch | [Viewer changelog](viewer-launch-changelog.md) | +| What languages and frameworks cover, and what's left | [Framework coverage](design/framework-coverage.md) | +| Validating a language or framework on real repositories | [Validation guide](AGENTS.md) and [coverage playbook](design/dynamic-dispatch-coverage-playbook.md) | +| Checking a language by hand | [Language verification guide](SEARCH_QUALITY_LOOP.md) | +| The browser viewer's design | [Viewer design spec](design/codegraph-ui-design-spec.md) | +| The native extraction kernel | [Kernel design](design/native-extraction-kernel.md) | + +## Supporting material + +- [Design](design/): architecture notes and feature proposals. Some describe planned work rather than what has shipped. +- [Benchmarks](benchmarks/): measurements and how they were taken. Read each against the revision and setup it records. +- [Grammars](grammars/): notes and patches for the parser grammars CodeGraph builds itself. +- [Plans](plans/): implementation plans. +- [Discussion notes](from-chat/): supporting notes from design discussions.