Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
89 lines (69 loc) · 3.31 KB

CONTRIBUTING.md

File metadata and controls

89 lines (69 loc) · 3.31 KB
Raw

Contributing to base-cli

Thank you for improving this project.

Please read the Code of Conduct before participating. Project roles, review expectations, and release continuity are documented in GOVERNANCE.md.

Development setup

The basectl shortcuts below are optional. Contributors working outside the Base workspace can run the same checks with the project’s standard Python tooling:

python3 -m pip install -e ".[dev,typer,quality,benchmark]"
./tests/full_validate.sh

Use the Python interpreter from your active virtual environment in place of python3 when necessary. The aggregate is the authoritative local gate and includes the framework-wide strict typing, documentation, benchmark, package, and security checks. Use ./tests/validate.sh for the fast repository-baseline check when the full extras are not installed; it is not a substitute for the aggregate.

Workflow

  1. Create or choose a GitHub issue before starting implementation work.

  2. Use exactly one standard issue category label: bug, enhancement, documentation, ci, or security.

  3. Create an issue-backed branch:

    <category>/<issue>-<YYYYMMDD>-<slug>

    The category prefix must match the issue's single standard category label. This branch shape is tool-independent; feat/, agent/, codex/, and bare issue-number prefixes are invalid.

  4. Use a dedicated Git worktree for each pull request so the main checkout can stay on the default branch:

    git fetch origin
git worktree add -b <branch> ../base-cli-worktrees/<slug> origin/<default-branch>

  5. Keep the pull request scoped to the issue and link it with Fixes #<issue> or Closes #<issue> when merge should close the issue.

  6. Run the project checks before opening or updating a pull request.

  7. Update CHANGELOG.md only for notable user-visible or release-worthy changes.

  8. After merge, sync the default branch, remove the worktree, and delete merged local and remote branches when safe:

    git pull --ff-only origin <default-branch>
git worktree remove ../base-cli-worktrees/<slug>
git branch -d <branch>
git push origin --delete <branch>

Useful commands:

These shortcuts are available to contributors using the Base workspace:

basectl check base-cli
basectl doctor base-cli
basectl test base-cli

AI Context Maintenance

Start AI-assisted orientation with .ai-context/INDEX.md. Maintain these curated summaries alongside meaningful changes to product scope, architecture, commands, or contributor workflows. Canonical docs and code remain the source of truth; update the pack when they disagree. State context impact in the PR, including a reason when no update is needed. Typo-only and internal changes without behavioral or architectural impact usually need no context update.

Validate changes with basectl export-context --list-files, basectl export-context --print, and python scripts/validate_docs.py from the checkout, plus git diff --check. The documentation validator includes .ai-context/*.md so links from the curated pack fail in CI when they drift. Keep the pack self-contained enough for offline reading, free of secrets and private runtime data, and independent of generated timestamps or export bundles.