docs: name the obligations CI enforces, fix accuracy defects #585
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -322,6 +322,20 @@ whose seams had diverged enough that several ports needed a different fix, and t | |
|
|
||
| ### Fixed | ||
|
|
||
| - **Contributor docs now name every obligation CI enforces.** `CONTRIBUTING.md` never mentioned | ||
|
There was a problem hiding this comment.
Both new entries are multi-sentence audit narratives spanning seven lines rather than terse, scannable, imperative release notes, so the actual change descriptions are buried in implementation history. Rewrite each as a short action-oriented bullet, moving rationale to the commit or PR description. AGENTS.md reference: AGENTS.md:L67-L68 Useful? React with 👍 / 👎. |
||
| `pyright` or the CHANGELOG, so its verify step — "`trunk check` and `uv run pytest -q` both | ||
| pass" — sent contributors into a CI failure on the dedicated typecheck job. It now carries | ||
| `uv run pyright`, the `## [Unreleased]` CHANGELOG contract, the Windows `PYTHONUTF8=1` | ||
| requirement and the Python 3.11 floor, the real extras (`tui`, `non-linux`, `opencode` — it | ||
| claimed only `tui`), and `scripts/release.py`'s two-phase `prepare`/`publish` flow. The pull | ||
| request template gains a matching Changelog section, as does CONTRIBUTING's copy of it. | ||
|
|
||
| - **The docs no longer describe a state the code has left behind.** The README's command table | ||
| gained `bmad-loop adapters`, and its docs list gained five missing guides plus `docs/README.md`, | ||
| the full index. `docs/FEATURES.md` now covers all 15 policy sections rather than 12 — `[dev]` was | ||
| documented nowhere. The roadmap's native-Windows entry read `planned` while its own body said | ||
| psmux had shipped, and `AGENTS.md` counted `~25` leaf modules where there are 28. | ||
|
|
||
| - **A failed ledger write can no longer empty the deferred-work ledger (#328).** `Path.write_text` | ||
| truncates the file and only then encodes, so any failure in that window — an unencodable value, | ||
| `ENOSPC`, `EIO` — left a zero-byte ledger with every entry gone. `append_decision`, | ||
|
|
@@ -2653,8 +2667,6 @@ for antigravity`, immediately after a successful `init --cli antigravity`). Both | |
| Still pending live E2E and a `usage_parser` — `probe-adapter` captures the token schema to write | ||
| one. | ||
|
|
||
| - **Adapter authoring guide.** New [adapter authoring guide](docs/adapter-authoring-guide.md) | ||
| walks through finalizing a CLI profile with `probe-adapter` (scan vs probe, the PII model, and | ||
| the parser-writing loop); `probe-adapter` is added to both command references. | ||
|
|
@@ -2727,6 +2739,9 @@ for antigravity`, immediately after a successful `init --cli antigravity`). Both | |
| - **MIT license + open-source community files.** The project is now MIT-licensed (© BMad Code, LLC) | ||
| with a trademark notice, and ships `CONTRIBUTING`, `SECURITY`, `CODE_OF_CONDUCT`, and GitHub | ||
| issue/PR templates as it becomes a first-class citizen in the BMAD org. | ||
| - **Uninstall procedure.** The [setup guide](docs/setup-guide.md#uninstalling) now documents a | ||
| full teardown — reclaim disk, remove `.automator/`, skills, hooks, and gitignore lines, then | ||
| `uv tool uninstall`. | ||
|
Comment on lines
+2742
to
+2744
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win Keep new entries under The new As per coding guidelines, every CHANGELOG entry must land under 🤖 Prompt for AI AgentsSource: Coding guidelines |
||
|
|
||
| ### Changed | ||
|
|
||
|
|
@@ -2737,12 +2752,6 @@ for antigravity`, immediately after a successful `init --cli antigravity`). Both | |
| [bmad-automator](https://github.com/bmad-code-org/bmad-automator) project is unrelated and stays | ||
| as-is. Re-run `uv tool upgrade bmad-auto --reinstall` to move an existing install onto the new name. | ||
|
|
||
| ## [0.5.0] — 2026-06-20 | ||
|
|
||
| ### Added | ||
|
|
@@ -3117,4 +3126,4 @@ enforced in CI. | |
| [0.3.1]: https://github.com/bmad-code-org/bmad-loop/commit/37dd884efaff | ||
| [0.3.0]: https://github.com/bmad-code-org/bmad-loop/commit/11a9d5a067a6 | ||
| [0.2.0]: https://github.com/bmad-code-org/bmad-loop/commit/823adae1c047 | ||
| [0.1.0]: https://github.com/bmad-code-org/bmad-loop/commit/274f0f5b6fd2 | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -74,23 +74,41 @@ After searching, use the [feature request template](https://github.com/bmad-code | |
|
|
||
| ## Development Setup | ||
|
|
||
| bmad-loop is a Python project managed with [uv](https://docs.astral.sh/uv/). **Python 3.11 is the floor.** | ||
|
|
||
| ```bash | ||
| git clone https://github.com/YOUR-USERNAME/bmad-loop.git | ||
| cd bmad-loop | ||
| uv sync --all-extras # deps + all three extras (tui, non-linux, opencode) + dev tools | ||
| uv run pytest -q # unit + adapter scenarios + tmux integration (-n auto to parallelize) | ||
| uv run pyright # typecheck — CI runs this same pinned version as its own job | ||
| ``` | ||
|
|
||
| Never `pip install` — uv owns the environment. If you change dependencies, edit `pyproject.toml` and run `uv lock`; CI uses `uv sync --locked` and fails on a stale lock. The pyright version is pinned exactly in the `dev` group, so bump it deliberately — never with `uv lock --upgrade`. | ||
|
|
||
| > **On Windows**, set `PYTHONUTF8=1` before running the suite — `tests/conftest.py` raises a `UsageError` without it. | ||
|
|
||
| Linting and formatting run through [trunk](https://trunk.io) (ruff, black, isort, prettier, markdownlint, and more). **Run `trunk check` before pushing** — a pre-push hook enforces it, so formatting/lint failures surface locally instead of in CI: | ||
|
|
||
| ```bash | ||
| trunk fmt # auto-format changed files | ||
| trunk check # lint + format verification, no path filter (what CI runs) | ||
|
Comment on lines
91
to
+95
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
rg -n -C 3 'trunk check|--all' CONTRIBUTING.md .github || trueRepository: bmad-code-org/bmad-loop Length of output: 4369 🏁 Script executed: #!/bin/bash
set -euo pipefail
printf '%s\n' '--- workflow references ---'
rg -n -i -C 5 'trunk|pre.?push|lint|format' .github .githooks .husky 2>/dev/null || true
printf '%s\n' '--- repository hook/config files ---'
git ls-files | rg -i '(^|/)(pre-?push|trunk|hooks?|lefthook|pre-commit|tox|nox|makefile|justfile|pyproject|package\.json|\.pre-commit-config)' || true
printf '%s\n' '--- workflow file excerpt ---'
if [ -f .github/workflows/ci.yml ]; then
cat -n .github/workflows/ci.yml | sed -n '1,190p'
fiRepository: bmad-code-org/bmad-loop Length of output: 15309 🌐 Web query:
💡 Result: The trunk-io/trunk-action@v1 does not have a static default command that equates to trunk check --all; instead, the action dynamically chooses its execution behavior based on the event context [1][2]. By default, trunk-io/trunk-action operates on changed files only: when triggered by a pull request, it checks all files changed in the PR, and when triggered by a push, it checks all files changed in that push [2]. To run a check on all files in the repository, you must explicitly configure the action by setting the check-mode input to all [3][2]: - name: Trunk Code Quality uses: trunk-io/trunk-action@v1 with: check-mode: all Additionally, the action automatically infers check-mode: all if the job is running as part of a scheduled or periodic workflow [2]. If you provide a trunk-token, the action also infers check-mode: all and will upload the results to the Trunk platform [2]. It is important to note that using check-mode: all or running "check all" in older configurations is often discouraged in favor of focused, incremental linting to maintain CI performance [4][2]. Citations:
🌐 Web query:
💡 Result: By default, the Trunk CLI runs the trunk check command in "hold-the-line" mode [1][2]. This means that when you execute trunk check without additional flags, it will only process and report issues on the files you have modified according to Git, by comparing your current work against the appropriate upstream branch [1][2]. If you wish to override this behavior and run checks on all files in your repository, you can use the --all flag [3][4]: trunk check --all This is particularly useful for identifying pre-existing issues throughout the entire project [2][5]. Additionally, you can customize the default behavior for your repository by configuring default command-line arguments in your trunk.yaml file [6]. Under the cli.options section, you can define default arguments that will be applied automatically whenever you run trunk check [6]. For example: cli: options: - commands: [check] args: --all Any command-line options provided manually during invocation will take precedence over these configured defaults [6]. Citations:
🏁 Script executed: #!/bin/bash
set -euo pipefail
printf '%s\n' '--- Trunk configuration ---'
cat -n .trunk/trunk.yaml
printf '%s\n' '--- contributor instructions ---'
cat -n CONTRIBUTING.md | sed -n '86,98p;136,145p'
printf '%s\n' '--- all tracked hook and Trunk references ---'
git ls-files | while IFS= read -r f; do
case "$f" in
*.yml|*.yaml|*.md|*.toml|*.json|*.sh|*.py|*.yaml.tmpl|*.yml.tmpl)
rg -n -i 'trunk check|trunk-action|pre.?push|check-mode|cli:|commands:' "$f" 2>/dev/null || true
;;
esac
doneRepository: bmad-code-org/bmad-loop Length of output: 8107 Correct the
🤖 Prompt for AI Agents |
||
| ``` | ||
|
|
||
| ### CHANGELOG | ||
|
|
||
| **Every user-visible change needs a CHANGELOG entry.** Add it under the `## [Unreleased]` heading in [CHANGELOG.md](CHANGELOG.md), and only under one of the six [Keep a Changelog](https://keepachangelog.com) subsections — `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`. Keep entries terse, scannable, and imperative. | ||
|
|
||
| Never open a new `## [X.Y.Z]` section yourself: a release _promotes_ `## [Unreleased]` into the version heading and reopens an empty one. `scripts/release.py check` enforces this contract in CI (the `version-sync` job). The full rule is in [AGENTS.md](AGENTS.md#repo-hygiene). | ||
|
There was a problem hiding this comment.
When cutting a release, this instruction can leave maintainers expecting AGENTS.md reference: AGENTS.md:L67-L69 Useful? React with 👍 / 👎. |
||
|
|
||
| ### Releases | ||
|
|
||
| Releases are cut by maintainers with `scripts/release.py`, which is two-phase: | ||
|
|
||
| - **`prepare X.Y.Z`** runs on a release branch — it validates that the CHANGELOG's `## [Unreleased]` section was promoted into `## [X.Y.Z]`, stamps the version everywhere via `sync_version.py`, regenerates TUI assets when they changed, and commits, leaving the branch ready for a PR. | ||
| - **`publish`** runs on `main` after that PR merges (driven by `.github/workflows/release.yml`) — it creates the tag and GitHub release from the CHANGELOG, and is idempotent. | ||
|
|
||
| Version strings are stamped only by `scripts/sync_version.py`; never hand-edit them in `pyproject.toml`, `module.yaml`, `marketplace.json`, or `uv.lock`. The version is validated in CI — if you touch it, run `uv run --no-project python scripts/sync_version.py --check`. | ||
|
|
||
| --- | ||
|
|
||
|
|
@@ -120,10 +138,11 @@ We will reject PRs that read like raw LLM output: bulk refactors nobody asked fo | |
| 2. **Clone** your fork: `git clone https://github.com/YOUR-USERNAME/bmad-loop.git` | ||
| 3. **Create a branch**: `git checkout -b fix/description` or `git checkout -b feature/description` | ||
| 4. **Make changes** — keep them focused | ||
| 5. **Changelog**: add an entry under `## [Unreleased]` in [CHANGELOG.md](CHANGELOG.md) for any user-visible change | ||
| 6. **Verify**: `trunk check`, `uv run pytest -q`, and `uv run pyright` all pass — CI runs all three | ||
|
There was a problem hiding this comment.
For changes affecting packaging, versions, or the changelog, contributors can follow this checklist successfully and still fail CI: AGENTS.md reference: AGENTS.md:L69-L69 Useful? React with 👍 / 👎. |
||
| 7. **Commit**: `git commit -m "fix: correct typo in README"` | ||
| 8. **Push**: `git push origin fix/description` | ||
| 9. **Open PR** from your fork on GitHub | ||
|
|
||
| ### PR Description Template | ||
|
|
||
|
|
@@ -144,6 +163,10 @@ Fixes #[issue number] | |
| ## Testing | ||
|
|
||
| [1-2 sentences on how you tested this] | ||
|
|
||
| ## Changelog | ||
|
|
||
| [Entry added under `## [Unreleased]` in CHANGELOG.md, under one of: Added, Changed, Deprecated, Removed, Fixed, Security. Write "n/a" if nothing user-visible changed.] | ||
| ``` | ||
|
|
||
| **Keep it under 200 words.** | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Adding this section makes the embedded “PR Description Template” in
CONTRIBUTING.mdstale: that block still ends after## Testing(CONTRIBUTING.md:147-166). Contributors who copy the documented template will omit the new changelog declaration, so update the embedded example alongside the GitHub template.Useful? React with 👍 / 👎.