Agentic Trader Docs

Contributing

Working style, branch hygiene, and the expectations that keep changes safe and readable.

Working style

This repo favors:

  • reading before coding
  • small, targeted diffs
  • explicit ownership boundaries
  • minimal abstraction
  • visible failures

Contribution rules that matter most

  • Do not rewrite working systems casually.
  • Prefer additive hardening over speculative rearchitecture.
  • Preserve local-first and paper-first assumptions unless the project direction changes explicitly.
  • Keep frontend shells thin around the Python runtime.
  1. read the smallest owning module
  2. read the matching docs and .ai notes
  3. make the minimal useful change
  4. run focused tests first
  5. run broader validation if behavior changed
  6. update docs and .ai notes when assumptions changed

Commit style

Conventional commit style is preferred because it keeps release automation and history readable. Examples:

  • feat: add locale-aware docs routing
  • docs: expand runtime and onboarding guidance
  • fix: clarify docs feedback forwarding state

Release automation reads conventional commits on main. Feature commits create minor releases, fix/perf/docs/build/ci/chore commits create patch releases, and ! or BREAKING CHANGE: marks a major release.

Only main mutates pyproject.toml, workspace package versions, and CHANGELOG.md automatically. Other branches run a version preview and may publish prerelease tags/releases for test binaries:

  • main: stable SemVer tags such as v0.9.5
  • V1, V2, and similar integration branches: next prereleases such as v0.9.6-next.9870+gabc1234
  • feature branches: beta prereleases such as v0.9.6-beta.9870+gabc1234

Do not use a fourth SemVer core segment like v0.9.5.9870; CI build identity belongs in prerelease or build metadata.

If the first stable main release needs to floor semantic-release to the tracked pre-1.0 baseline, the release workflow creates a baseline changelog section before tagging so CHANGELOG.md does not stay empty.

CI and release checks

Pull requests and protected branches should keep these checks green:

  • Python core: uv sync, Ruff, Pyright, Pytest, and a PyInstaller smoke build
  • Web GUI: pnpm workspace install, lint, typecheck, and production build
  • Docs: pnpm workspace install, lint, typecheck, and static export
  • TUI: pnpm workspace install and Ink entrypoint syntax check
  • Version Check: semantic-release preview plus SemVer-compatible branch artifact identity
  • Binaries: PyInstaller macOS and Windows artifacts for branch testing, attached to stable releases on v* tags and to prerelease GitHub Releases on branch pushes

Strict Pyright/Pylance is active, but the repository is still burning down a documented legacy backlog. CI and release checks use scripts/check_pyright_baseline.py as a regression gate: new diagnostics above the current baseline fail, while type-cleaning work should lower the baseline in the script, roadmap, and .ai state together.

When docs updates are part of the task

Docs should be updated in the same branch when:

  • a command or workflow changed
  • the frontend or runtime boundary changed
  • a new guardrail or design rule was introduced
  • onboarding expectations moved

What makes a good PR in this repo

  • the diff stays focused
  • operator-visible behavior is verified
  • docs match the implementation
  • future contributors do not have to rediscover the same rule from scratch
How was this page?
This GitHub Pages build prepares a browser-local feedback draft and a prefilled GitHub issue. Node-hosted local docs can still wire feedback into runtime logs later.

Stores a draft in this browser and gives you a GitHub issue link to submit when ready.

QA And Debugging

Validate operator-facing changes with targeted tests, smoke QA, and runtime evidence.

On this page

Working styleContribution rules that matter mostRecommended contribution flowCommit styleCI and release checksWhen docs updates are part of the taskWhat makes a good PR in this repo