Skip to content

Contributor And Local Development

Purpose

This page is the bounded operator entrypoint for day-to-day work in Ledger.

Use it when you need to answer practical questions such as:

  • how should work start in this repo
  • where is the canonical local-dev path
  • which conventions shape docs and repo edits
  • which GitHub intake and PR surfaces are part of the governed contribution path
  • how should merge happen on ledger/main

It does not replace the underlying canon. It points to the high-signal surfaces you should actually use.

Contributor Surface Map

flowchart TD
    A["Contributor / operator"] --> B["Repo README"]
    A --> C["Local development"]
    A --> D["Repo conventions"]
    A --> E["Issue intake"]
    A --> F["PR governance"]
    A --> G["Merge path"]

    C --> C1["Local dev stack runbook"]
    C --> C2["Bootstrap standard"]
    C --> C3["Env contract"]
    C --> C4["Devcontainer standard"]

    D --> D1["Structure convention"]
    D --> D2["Naming convention"]
    D --> D3["README section standard"]

    E --> E1["Issue form"]
    F --> F1["PR template"]
    F --> F2["PR governance model"]
    G --> G1["Merge queue path for ledger/main"]

Start Here: Repo README

Start here Why it matters High-signal anchors
README.md the fastest practical summary of what Ledger is and how to work in it Working Agreements / Governance, Local Development / Operating Notes, How to Contribute, Contract Validation

Use this when:

  • you need the fastest repo-level orientation
  • you need the top-level contribution and local-dev anchors
  • you want the shortest route into the right governed surface

Local Development

Surface Start here Why it matters
local-dev runbook docs/local-dev/LOCAL_DEV_STACK_v0.1.md canonical bring-up order and smoke path
bootstrap doctrine governance/BOOTSTRAP-STANDARD.md deterministic bootstrap expectations across repos
environment contract governance/ENV-CONTRACT.md shared variable ownership and placeholder rules
devcontainer standard governance/lifecycle/DEVCONTAINER-STANDARD.md expectations for reproducible developer environments

Use these when:

  • you are bringing Ledger or the local Orbitra stack up from a clean machine
  • you need the expected local commands and dependency order
  • you need to know which env variables and toolchain assumptions are governed

Working rule:

  • use the runbook for operator steps
  • use the bootstrap and env contracts for required behavior
  • use the devcontainer standard for environment reproducibility expectations

Repo Conventions

Surface Start here Why it matters
structure governance/DOC-STRUCTURE-CONVENTION.md canonical Ledger root surfaces and placement rules
naming governance/DOC-NAMING-CONVENTION.md deterministic naming for docs, evidence, ADRs, and RFCs
README shape governance/README-SECTION-STANDARD.md required README section order and expectations

Use these when:

  • you are adding or moving docs
  • you are naming new governance or evidence artifacts
  • you are deciding where a new file belongs

Issue Intake

Surface Start here Why it matters
docs issue form .github/ISSUE_TEMPLATE/docs.yml canonical intake shape for docs-only Ledger work
issue governance model docs/operating-system/models/ISSUE_GOVERNANCE_AND_NORMALIZATION_MODEL.md how issue metadata, normalization, and advisory automation are interpreted

Use these when:

  • you are creating a new bounded MkDocs or docs-only task
  • you need the field shape that GitHub governance expects
  • you need to understand why a label such as needs-routing-metadata appears

PR Governance And Merge Path

Surface Start here Why it matters
PR template .github/pull_request_template.md required PR body shape for governed work
PR governance model docs/operating-system/models/PULL_REQUEST_EXECUTION_GOVERNANCE_MODEL.md issue-to-PR execution rules, queue compatibility, and closeout expectations
review and closeout playbook docs/operating-system/playbooks/REVIEW_AND_CLOSEOUT_PLAYBOOK.md practical review, acceptance, and done path

Use these when:

  • you are preparing a PR
  • you need the required review and closeout shape
  • you need to know whether merge is enough for closure

Merge Queue Rule For ledger/main

For ledger/main, merge queue is the default merge path.

Use the PR governance model when you need the exact operator rule. The practical interpretation is:

  1. get the PR into a truthful review state
  2. ensure required checks are green on the PR
  3. enter the merge queue instead of habitually merging directly
  4. wait for merge-group checks and final merge completion before treating the issue as closed

That means the queue path is part of the governed contributor workflow, not an optional GitHub detail.

Validation Entry Points

High-signal validation anchors for Ledger contributors:

Use these when:

  • you need the fastest validation path for repo-local work
  • you need to confirm what should run before review or closeout

For the broader validation, standards, spec, and proof map, continue to this site's Validation, Standards, And Evidence page.

Working Rule

Use this page as a routing page, not as a replacement for canon.

Start from:

  1. repo README
  2. the specific local-dev or convention surface you need
  3. issue form and PR governance when the work becomes governed execution
  4. merge queue as the default final integration path for ledger/main