Skip to content

docs: add a five-minute first-contribution path - #49

Merged
SignalLayerLabs merged 1 commit into
SignalLayerLabs:mainfrom
dchaudhari7177:docs/first-contribution-v2
Aug 19, 2026
Merged

docs: add a five-minute first-contribution path#49
SignalLayerLabs merged 1 commit into
SignalLayerLabs:mainfrom
dchaudhari7177:docs/first-contribution-v2

Conversation

@dchaudhari7177

Copy link
Copy Markdown
Contributor

Closes #34.

Adds docs/project/first-contribution.md, linked from the top of CONTRIBUTING.md and from docs/index.md under Project.

Acceptance criteria

  • Concise first-contribution page, linked prominently from CONTRIBUTING.md — the link sits directly under the opening line, before Principles.
  • Shows clone / editable install / one focused test / full pre-PR checks — in that order.
  • Explicitly says examples and fixtures must use synthetic identifiers — stated in full with the reason, not just cross-referenced.
  • Does not weaken existing privacy, benchmark or compatibility requirements — see below.
  • All documentation links remain valid — 29 relative links across the three touched files checked; none broken.

On not weakening the contract

This was the criterion I was most careful about, since a "quick start" page is exactly where standards get quietly softened. Two deliberate choices:

  • The page opens by saying the standards in CONTRIBUTING.md apply to a one-line docs fix exactly as to a new adapter.
  • The pre-PR check list is reproduced verbatim and complete — format, lint, mypy, pytest, build, twine — rather than an abbreviated "just run pytest". An abbreviated list would become the de facto standard.

The synthetic-identifier rule is quoted in full with its rationale: fixtures end up in exports, so a real name in a fixture is a privacy incident that outlives the PR.

It also flags the asymmetry a newcomer is most likely to trip on: new behavior requires a failing test before implementation, whereas adding coverage for behavior that already exists does not — which is why the latter is recommended as a starting point.

Verification

Every command in the page was actually run against this tree, not copied from CONTRIBUTING.md on faith:

command result
pytest tests/test_budget.py -q 12 passed
pytest tests/test_budget.py -q -k reservation 2 passed, 10 deselected
ruff check src tests examples All checks passed
python examples/shadow_mode.py exit 0
python examples/universal_runtime.py exit 0

Note

I deliberately did not link the capability glossary from #37 here, so this PR stands alone and neither depends on merge order. The relevant sentence points at the existing integrations/overview.md#integration-labels instead. Happy to add the glossary link in a follow-up once #37 lands.

CONTRIBUTING.md documents the standards a change must meet, but a first-time
contributor still has to infer where a small safe change can begin. Add
docs/project/first-contribution.md covering the other half: clone, editable
install, one focused test, then the full pre-PR checks.

Named low-risk starting points: documentation, synthetic fixtures, the
executable examples, and tests for behaviour that already exists. The last one
notes the asymmetry in CONTRIBUTING -- new behaviour needs a failing test
first, whereas covering existing behaviour does not, which makes it the easier
entry point.

The synthetic-identifier rule is stated explicitly rather than referenced,
with the reason: fixtures reach exports, so a real name in a fixture outlives
the pull request.

Nothing here relaxes an existing requirement. The page says so in its opening,
and repeats the full pre-PR check list verbatim rather than an abbreviated
version, so it cannot drift into looking like a lighter path.

Every command in the page was run against this tree: pytest on a single file
and with -k, the ruff checks, and both executable examples.

Linked from the top of CONTRIBUTING.md and from docs/index.md under Project.

Closes SignalLayerLabs#34
@SignalLayerLabs
SignalLayerLabs merged commit 5a8a138 into SignalLayerLabs:main Aug 19, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

2 participants