Skip to content

docs: say how to accept a draft and merge the Changed headings - #954

Merged
austinborn merged 2 commits into
mainfrom
docs/draft-acceptance-and-changelog-heading
Nov 18, 2026
Merged

austinborn merged 2 commits into
mainfrom
docs/draft-acceptance-and-changelog-heading

Conversation

@austinborn

@austinborn austinborn commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Summary

This follows up the review on #948, whose first two points arrived after that PR merged.

  • CHANGELOG.md: Unreleased had two ### Changed headings. The README bullet now sits in the first section, so the release keeps one heading per type, as Keep a Changelog expects. No bullet text changed.
  • README.md and docs/GETTING_STARTED.md: "Adding decisions" said a draft written from a coding agent's shell is read by no check until its status is accepted, but not how to accept it. Both now say to change status: draft to status: accepted in the header of both files adr new wrote, and the decision file's Status: proposed line to Status: accepted. A second sentence notes that an agent passing --status accepted writes an accepted decision in the first place. Both hold on 0.14.0 and on main.

The review's third point, the README paragraph that repeats the new section's actual adr new sentence, waits on #943, which rewrites that paragraph. It's tracked for a trim once #943 merges.

Risk is low, since only docs change. #930 and #950 append CHANGELOG bullets where the two headings meet, so whichever merges after this one resolves a two-line conflict there. Other open PRs on these files conflict no more than they already do.

Verification: none, docs only
The new sentences were checked against the released 0.14.0 CLI in a scratch repository (details below).

Test plan and overlapping pull requests

Test plan

The released actual 0.14.0 binary ran in a scratch git repository, with telemetry off through a scratch config directory:

  1. actual adr new "Use Postgres for storage" --policy "MUST: Services store relational data in Postgres." < /dev/null (no terminal, as in an agent's shell) wrote both files with status: draft, and actual rules ls listed the rule as MUST 1 (draft, not enforced).
  2. Changing status: draft to status: accepted in the rule file's header made actual rules ls list the rule as enforced, since the checks read the rule file under .actual/rules/. The decision file's header and its Status: proposed line change too, so the file reads as one written with --status accepted does (Status: accepted below the header). No check or save reads that line, and actual adr check --no-cloud passed with all three changed.
  3. actual adr new "Use Redis for caching" --policy "MUST: Services cache through Redis." --status accepted < /dev/null wrote both files with status: accepted, printed "It is accepted, so plan-check and impl-check enforce it now", and actual rules ls listed the rule as enforced.

--status accepted|draft appears in 0.14.0's actual adr new --help and in its docs/ADR_COMMANDS.md, and the README already marks adr new as CLI 0.14.0 or later, so the new sentences need no version note of their own. The status list that decides whether a rule governs (src/rules/types.rs:228) is unchanged between v0.14.0 and main.

Pushing a draft with actual adr create --file wasn't exercised, since it needs a sign-in and saves to Actual AI, so the docs don't offer it as a way to accept a local draft.

Overlapping pull requests

git merge-tree --write-tree of this branch against each open PR that edits these files, beside main against the same PR:

PR Shared files main and the PR this branch and the PR
#930 CHANGELOG.md merge cleanly conflict in CHANGELOG.md
#950 CHANGELOG.md merge cleanly conflict in CHANGELOG.md
#943, #951 CHANGELOG.md, README.md merge cleanly merge cleanly
#923, #924, #945, #953 CHANGELOG.md merge cleanly merge cleanly
#797, #812, #869, #913 CHANGELOG.md or README.md already conflict conflict in the same files

Generated by the operator's software factory.
• City: city · Agent: local-core__builder-ci-wisp-r28ve8
• On behalf of: @austinborn

…raft

Unreleased had two `### Changed` headings. The README bullet now sits
in the first one, so the section follows Keep a Changelog's one heading
per type.

The README and Getting Started said a draft written from a coding
agent's shell is read by no check until its status is accepted, but not
how to accept it. Both now name the two ways that work on 0.14.0:
change `status: draft` to `status: accepted` in the header of both
files, or have the agent pass `--status accepted`.

City: city · Agent: local-core__builder-ci-wisp-r28ve8
Accepting a draft by hand now also changes the decision file's
`Status: proposed` line below the header. No check reads it, but it is
what a person reading the decision sees, and `adr new --status
accepted` writes `Status: accepted` there. `--status accepted` doesn't
accept an existing draft; it makes `adr new` write an accepted decision
in the first place, so it now has a sentence of its own.

City: city · Agent: local-core__builder-ci-wisp-r28ve8
@austinborn
austinborn added this pull request to the merge queue Nov 18, 2026
Merged via the queue into main with commit e969a5d Nov 18, 2026
10 checks passed
@austinborn
austinborn deleted the docs/draft-acceptance-and-changelog-heading branch November 18, 2026 22:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants