Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

SPACE 0.8.1

Contributing to SPACE

Thank you for your interest in SPACE. SPACE is open source, and we welcome thoughtful bug reports and proposals. Our maintenance team is still building the capacity to review and support outside contributions, so we ask you to discuss most changes before writing code.

Propose a change

Search existing issues, then open one describing the problem, why it matters, and your proposed approach. Include your self-assessed severity and a brief reason for it. If an AI agent drafted the issue, say so. The SPACE team will triage proposals and decide which work to take on.

Please wait for a maintainer to agree on the scope before opening a pull request, except for trivial bug fixes. A maintainer agrees by labeling the issue triage:accepted. Put Fixes #<issue> in the pull request description so it goes straight to review. Agreement to proceed does not guarantee that a pull request will be merged.

Report suspected vulnerabilities privately as described in SECURITY.md, rather than in a public issue or pull request.

Contributor license agreements

Before your first contribution is merged, sign the Individual Contributor License Agreement (ICLA) through CLA Assistant, unless your account has a maintainer-approved exemption or your contribution is covered by a confirmed corporate agreement.

For contributions on behalf of a company, review the Corporate Contributor License Agreement (CCLA) and contact space-team@perplexity.ai to arrange signature by an authorized company representative and confirmation of the covered GitHub accounts.

Agent-assisted contributions

For agent-assisted work, disclose AI assistance in the pull request description instead of adding automation-only Co-authored-by trailers.

Before your first commit

Install pre-commit and the repository hooks in each clone, using uv:

uv tool install pre-commit
pre-commit install --install-hooks

The pinned Gitleaks hook scans staged changes before Git creates a commit and redacts detected values. Initial setup builds the scanner with Go; pre-commit 3+ can download Go if it is absent, so allow network access for setup. Run pre-commit run gitleaks to check staged changes manually.

Before committing, ask your agent to use the space-public-review skill on the staged change, or follow it as a manual checklist. Bring private issues upstream through clean reproductions with synthetic inputs and caller-supplied configuration. Remove any credentials the hook reports rather than bypassing it.

Known public test fixtures have exact-value, exact-path exceptions in .gitleaks.toml. For a new false positive, establish that it is intentionally public test material and propose an equally narrow exception with its reason; do not exclude whole files or test directories.

These checks cover staged changes, not history; review surrounding staged content because diff scans can miss edits inside existing multiline keys.

Run the tests

Tests that need Postgres or Redis start them in Docker, so run them with a reachable Docker daemon. cargo nextest run starts one shared Postgres and Redis per run through the setup scripts in .config/nextest.toml; build cargo build -p pplx-space-db-test-fixtures --bin space-nextest-postgres-setup first when you select packages with -p. Other runners start a container per test. ci/scripts/run-python-tests.sh starts the Postgres the Python tests use.

These dependencies are required: when one is unavailable, each test that needs it fails and names it. To run without them, set SPACE_TEST_DEPS_OPTIONAL=1; those tests then skip, each printing a SPACE-TEST-DEP-SKIP: line, and validate nothing. Opted out, cargo nextest run and ci/scripts/run-python-tests.sh also start no Postgres when Docker is not reachable, and say so with the same marker. A few Rust tests use fixtures that never skip, such as pg_test_db, and fail even then.

CI sets SPACE_CI_REQUIRE_TEST_DEPS=1, which overrides the opt-out. Don't set that variable yourself: the fixtures still read it set to empty or 0 as optional, for older callers, but the NoCoW host-filesystem tests treat any value of it as a CI run and fail without their fixture.

Tests that need root or a disposable host filesystem have their own opt-ins, which this does not turn on; see "Privileged tests and the CI host" in docs/rust/space-conventions.md.

Submit a pull request

Keep the change focused and link the relevant issue when there is one. Start the pull request description from the template. It asks what merging the change does and why, and how you validated it. It also asks for your self-assessed severity with a brief reason, or a note that severity does not apply, and what the change could break. Disclose whether an AI agent drafted the pull request description or contributed to the change, and identify those parts. Size the description to the risk of the change, not to the effort behind it.

Many readers see the description long after the pull request merges, and they can see only this repository:

  • Describe what merging the pull request does, not how the pull request got there. Answer review in comments and commits, and keep the description current.
  • Link each reference to something a reader can open: an issue, a pull request, a commit on main, or a file in this repository. Otherwise, state the point directly.
  • Open an issue for each follow-up you find, and link it. Nobody tracks a finding recorded only in a merged pull request's description.
  • Before you mark the pull request ready for review, check each claim, commit, and result in the description against the current head.

Pull CI runs the Kind/Firecracker smoke only when a pull request changes a path in ci/kind-pull-paths.txt. On a draft it is deferred, and the required space-pull-ci check fails until it runs. It runs when you mark the pull request ready for review, and on every push while it stays ready; converting it back to a draft defers it again. To run it on a draft, someone with triage access adds the kind-smoke label, and it runs from the next push.

Run cargo arch to check the repository structure rules in ARCHITECTURE.toml; archcheck explains each rule and its baseline.

For larger work, consider using gh stack to split it into a patch stack. Keep each pull request small enough for a human reviewer to reason about, but complete in scope so it can be understood and validated on its own. Explain how each pull request depends on the others and fits into the full stack.

The SPACE team will triage and review pull requests according to project priorities and available maintenance capacity. We may decline a contribution, including a technically sound one, if we cannot responsibly review or maintain it. We will aim to explain that decision when we can.

Longer-term participation

If you or your organization are interested in sustained participation, please contact space-team@perplexity.ai.