Skip to content

Docs: contributor onboarding commands incomplete/inconsistent across CONTRIBUTING.md and Copilot instructions #1948

Description

@codeforester

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

  • CONTRIBUTING.md's Contributor Setup section either has the
    contributor clone base-cli alongside base-bash-libs, or clearly
    explains that it's only needed for the Python test command shown
    later, with a pointer at that point.
  • Every copy of the linked-worktree base-test command in these docs
    includes BASE_CLI_SOURCE_DIR, matching docs/testing.md's
    explanation of why it's required.
  • .github/copilot-instructions.md's validation command matches (or the
    doc explains why it intentionally differs from) AGENTS.md/
    CONTRIBUTING.md.

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)

Metadata

Metadata

Assignees

Labels

documentationDocumentation improvements

Type

No type

Projects

Status
Backlog

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions