Contributing

You can contribute to 10xGraph by fixing bugs, improving the code, writing documentation, or adding examples. The project is MIT licensed and developed in the open across four repositories: the Python framework, the API server and CLI, the TypeScript client, and this docs site. Pick the one that matches your change.

Every page here has an Edit this page link at the bottom that opens the right file in the docs repository.

Contributing to the framework

The core library uses uv:

git clone https://github.com/10xGraph/10xGraph
cd 10xGraph
uv sync --dev              # create .venv and install the package plus dev tools
uv run pre-commit install  # enable the git hooks

Install the extras for whatever subsystem you are working on:

uv pip install -e ".[google-genai,openai,anthropic,mcp,pg_checkpoint]"

Before opening a pull request:

uv run pytest --cov --cov-branch   # tests plus the 80% coverage gate
uv run ruff check . && uv run ruff format .
uv run mypy tenxgraph/             # new code is type-checked

Tests that need a real Redis or Postgres are marked integration and are skipped by default. Pass --integration once you have the services up.

The full guide, including the code of conduct, lives in CONTRIBUTING.md in each repository.

What a good pull request looks like

• One concern per pull request. A fix plus a refactor is two pull requests.
• A test that fails before the change and passes after it.
• A changelog entry under ## [Unreleased] in CHANGELOG.md, under the same headings that file already uses (Breaking, Changed, Added, Fixed, Migration). Breaking changes must include the migration step.
• Public API changes come with docs. A new parameter that appears nowhere on this site does not exist as far as users are concerned.

Contributing to these docs

The docs are a static Astro site. Pages are .md or .mdx files under src/content/docs/, and the folder path is the URL path. Node 22.12 or newer is required.

git clone https://github.com/10xGraph/10xgraph-docs
cd 10xgraph-docs
npm install
npm run dev        # builds the search index, then serves http://localhost:4321

Checks that must pass before a pull request:

npm run check      # type-check .astro and .ts files
npm run build      # validates every page's frontmatter, then builds and indexes

Frontmatter is validated by the collection schema in src/content.config.ts, so a page with a missing or out-of-range field fails the build.

Where a page belongs

Put a page where its reader is, not where its topic is. The section field in the frontmatter must be one of the sections below.

If a topic needs coverage in more than one section, write the reference page and link to it. Do not restate the same parameter table in four places.

Writing conventions

• Frontmatter: title, description (50 to 170 characters), section, and order are the core fields. seoTitle (15 to 49 characters), group, label, updated, and faq (items with q and a) are optional.
• Open with the answer. Start each page with a 40 to 60 word paragraph that answers the page’s question on its own.
• Verify before asserting. Read the source for the signature, the default, and the error message. Prefer a short complete example over a long partial one.
• Every code block should run. Use real import paths such as from tenxgraph.core.graph import StateGraph.
• Link with absolute docs paths such as /docs/concepts, and only to pages that exist.
• Moving or renaming a page requires a redirect in src/redirects.json.
• Components such as Callout and Tabs work only in .mdx files. Plain .md pages use Markdown only.