Goal
Fix contributor-onboarding docs so the setup and validation commands they
give actually work as written, and so Copilot isn't given a different
validation command than every other contributor/agent.
Background
A documentation review of the process/CI/agent docs found several onboarding
commands that are incomplete or inconsistent with each other:
CONTRIBUTING.md:76-97 ("Contributor Setup") only tells a new contributor
to clone base-bash-libs, never base-cli — yet the pytest command given
later in the same file (CONTRIBUTING.md:118-122) requires a base-cli
sibling checkout (BASE_CLI_SOURCE_DIR=../base-cli/lib/python).
CONTRIBUTING.md:127-132's base-test command for the "linked worktree"
scenario omits BASE_CLI_SOURCE_DIR, but docs/testing.md:124-138
explains that this exact scenario
(~/work/base-worktrees/<slug>) breaks the sibling base-cli lookup and
requires that variable — two of the three docs that give this command give
an incomplete version.
.github/copilot-instructions.md:39 tells Copilot to validate general
changes with env -u BASE_HOME ./bin/base-test, while AGENTS.md:121 and
CONTRIBUTING.md:142 instruct basectl test base for the same case —
Copilot is given a different validation command than every other agent
workflow described in the repo.
Scope
CONTRIBUTING.md
.github/copilot-instructions.md
docs/testing.md (only if a cross-reference needs adding)
Acceptance Criteria
Validation
Follow CONTRIBUTING.md's Contributor Setup + Running Tests steps literally
on a clean checkout and confirm each given command succeeds without needing
an undocumented extra step.
Non-Goals
- Changing the actual test/setup tooling — this is about making the
documented commands correct and consistent.
Project Metadata
- Priority: P1
- Size: M
- Area: Docs
- Initiative: Adoption Polish
- Agent Assignment: Copilot candidate after triage (mechanical command
reconciliation, verifiable by literally running the documented steps)
Goal
Fix contributor-onboarding docs so the setup and validation commands they
give actually work as written, and so Copilot isn't given a different
validation command than every other contributor/agent.
Background
A documentation review of the process/CI/agent docs found several onboarding
commands that are incomplete or inconsistent with each other:
CONTRIBUTING.md:76-97("Contributor Setup") only tells a new contributorto clone
base-bash-libs, neverbase-cli— yet the pytest command givenlater in the same file (
CONTRIBUTING.md:118-122) requires abase-clisibling checkout (
BASE_CLI_SOURCE_DIR=../base-cli/lib/python).CONTRIBUTING.md:127-132'sbase-testcommand for the "linked worktree"scenario omits
BASE_CLI_SOURCE_DIR, butdocs/testing.md:124-138explains that this exact scenario
(
~/work/base-worktrees/<slug>) breaks the siblingbase-clilookup andrequires that variable — two of the three docs that give this command give
an incomplete version.
.github/copilot-instructions.md:39tells Copilot to validate generalchanges with
env -u BASE_HOME ./bin/base-test, whileAGENTS.md:121andCONTRIBUTING.md:142instructbasectl test basefor the same case —Copilot is given a different validation command than every other agent
workflow described in the repo.
Scope
CONTRIBUTING.md.github/copilot-instructions.mddocs/testing.md(only if a cross-reference needs adding)Acceptance Criteria
CONTRIBUTING.md's Contributor Setup section either has thecontributor clone
base-clialongsidebase-bash-libs, or clearlyexplains that it's only needed for the Python test command shown
later, with a pointer at that point.
base-testcommand in these docsincludes
BASE_CLI_SOURCE_DIR, matchingdocs/testing.md'sexplanation of why it's required.
.github/copilot-instructions.md's validation command matches (or thedoc explains why it intentionally differs from)
AGENTS.md/CONTRIBUTING.md.Validation
Follow
CONTRIBUTING.md's Contributor Setup + Running Tests steps literallyon a clean checkout and confirm each given command succeeds without needing
an undocumented extra step.
Non-Goals
documented commands correct and consistent.
Project Metadata
reconciliation, verifiable by literally running the documented steps)