Steward
Sign in

Documentation › Contributor guides

Sandbox issues

A sandbox issue is a low-stakes, well-defined task that maintainers seed for new contributors to claim and finish. The escrow system around them is Steward's answer to the chicken-and-egg problem of new contributors: you need reputation to merge in restricted domains, but you can't earn reputation without merging. Sandbox issues are the on-ramp.

This doc covers the two ways you interact with sandbox issues: voluntarily (you ask for one) and involuntarily (your PR lands in restricted territory and Steward routes you through sandbox first).

Voluntary: /steward sandbox-me

The easiest path. Drop this on any PR or issue thread:

/steward sandbox-me

Steward picks an open issue labelled with the repo's sandbox label, assigns it to you, and posts:

@alice — assigned sandbox issue #142 to you. Closing it as
merged increases your reputation in that domain.

You go finish the issue, open a PR, get it merged. The merge emits a PR_MERGED event in the relevant domain — your first reputation points land.

If no sandbox-labelled issues are open right now, you'll see:

@alice — no `sandbox`-labeled issues are currently available.
Check back when the maintainers seed the backlog.

That's an honest signal — wait, or pick a different repo, or contribute outside the sandbox pipeline (any merged PR earns reputation, sandbox just lowers the friction).

When this is the right move

  • You're new to the repo and want to build authority before tackling something ambitious.
  • You're already a regular contributor but want to add reputation in a domain you don't usually touch.
  • You're an experienced contributor who wants to mentor a teammate by walking them through a sandbox-grade task.

When this isn't the right move

  • You already have substantial reputation in the domain. Save sandbox issues for newer contributors.
  • The repo's sandbox label is for narrow purposes (some maintainers use it for "good first issue" specifically; others use it as Steward intends, for any reputation-building task). Read CONTRIBUTING.md to be sure.

Involuntary: escrow

The other way you encounter sandbox issues is when Steward forces you through them. This happens when:

  1. You open a PR that touches files in one or more restricted domains (governance.pxf domains with restricted: true).
  2. Your reputation in those domains is below their approval_threshold.

Rather than rejecting your PR, Steward puts it in Escrow status and posts:

Hi @alice — your PR has been escrowed.

This change touches the following restricted domains where
your reputation is below threshold:
  - `auth`: 0.40 < threshold 2.00
  - `core`: 1.10 < threshold 3.00

Per the Escrow Pipeline (governance.pxf), 3
`sandbox`-labeled issues will be assigned to you. Once they
merge, this PR will be unlocked for community voting
automatically.

What that means concretely:

  • Your PR stays open but can't merge yet — it's in escrow. The maintainer + reviewers can comment normally.
  • Steward assigns you N sandbox issues (where N is the repo's escrow.sandbox_issue_count, typically 2–5).
  • You go finish the sandbox issues. Their merges build your reputation in the relevant domains.
  • Once enough sandbox issues merge to lift your reputation above the thresholds, your original PR unlocks automatically for community voting (the cross-domain consensus surface).

Why "escrow" and not "rejection"

The intent is to convert a "we don't know you well enough to trust this yet" signal into "here's how to earn that trust." Rejecting an outright unqualified-domain PR loses the contributor. Escrowing it keeps them engaged + builds the authority needed to merge the work they wanted to do in the first place.

The downside is that escrow takes time — finishing N sandbox issues isn't instant. If you're under time pressure, ask the maintainer if a review-and-merge path is available; some maintainers will approve under their own authority if the work is genuinely needed.

Auto-generation when the backlog is short

A repo might not have enough sandbox-labelled open issues to assign N. Steward handles this in two ways:

  1. Auto-generate — if the repo's governance.pxf declares escrow.sandbox_templates, Steward creates new sandbox issues from the templates to make up the shortfall. You'll see fresh issues appear with template titles like "Add a test for X" or "Refactor Y into smaller functions."
  2. Error out — if there's no template config and the backlog is short, escrow fails with a maintainer-side error. Your PR stays in pending state until the maintainer either seeds more sandbox issues or removes the restricted-domain constraint.

Either way, you'll know — the comment Steward posts tells you what happened.

What counts as "sandbox-finished"?

A sandbox issue is "finished" when its closing PR is merged. The merge:

  1. Closes the GitHub issue (via the usual Closes #N or Fixes #N trailer in the PR description).
  2. Emits a PR_MERGED event with the relevant domain (determined by the changed files' path_globs).
  3. In escrow mode, also updates the escrow link state — if it was the Nth sandbox you needed, your original PR transitions out of escrow.

You don't need to do anything special on the sandbox PR beyond a clean merge. Steward's escrow tracking watches the PR_MERGED events and updates state automatically.

Reputation earned via sandbox vs regular PRs

A merged sandbox PR earns reputation by the same formula as any other merged PR (Reputation as a contributor):

points = base × (1 + ln(complexity)) × criticality

Sandbox issues tend to be small (one of the points of them), so the complexity term is usually 1 and the earn is typically just base × criticality. Modest, but it accumulates.

There's no bonus and no penalty for using the sandbox path vs going straight at substantial work — the math is the same. Sandbox just lowers the friction for new contributors by giving them a clear list of "ok to take on" tasks.

For maintainers: configuring the sandbox pipeline

The maintainer-side config lives in governance.pxf:

escrow: {
  sandbox_issue_count: 3
  sandbox_labels:      ["sandbox", "good first issue"]
  sandbox_templates: [
    { title: "Add test coverage for ${pkg}", body: "..." }
    { title: "Document ${pkg}'s ${exported_name}", body: "..." }
  ]
}
  • sandbox_issue_count — how many sandbox issues an escrow'd contributor must merge to unlock their original PR.
  • sandbox_labels — which GitHub labels Steward looks for when picking issues. Multi-label is OR; the slash command picks one at random.
  • sandbox_templates — optional. When set, Steward auto-generates new sandbox issues from these templates if the backlog is short.

Maintainers should treat the sandbox backlog as a curation surface — keep it healthy if you want contributors to use it. The sandbox_templates auto-generation is a safety net, not a substitute for genuinely useful tasks.

What's next