Skip to content

[repo]: split docs/ai into one file per entry - #1253

Merged
seunlanlege merged 1 commit into
mainfrom
docs-ai-one-file-per-entry
Sep 10, 2026
Merged

seunlanlege merged 1 commit into
mainfrom
docs-ai-one-file-per-entry

Conversation

@seunlanlege

Copy link
Copy Markdown
Member

The problem

Every package under sdk/packages/* kept three shared files in docs/ai/ChangeLog.md, Decisions.md and Flow.md. All three were append-only with newest entries on top, so any two concurrent PRs wrote the same line and GitHub marked both conflicted.

#1251 declared merge=union for the two log files. That fixes it locally and does nothing on GitHub, which ignores merge drivers when it computes a PR's mergeability.

Measured on #1250, which changes nothing but those two logs and one test file, and whose merge base is the .gitattributes commit itself:

Merge of #1250 into main Result
locally, with merge=union clean
locally, with the union lines removed conflicts in ChangeLog.md and Decisions.md
GitHub mergeable: false, dirty

Same two commits, same base SHA.

The change

Each entry is now its own file:

sdk/packages/simplex/docs/ai/
  README.md
  changelog/2026-09-10-guard-the-socket-mode-wizard-announcement-for-json-output-1237.md
  decisions/2026-09-10-run-s-flags-live-in-src-cli-run-options-ts-not-in-the-bin.md
  flows/order-intake-what-reaches-the-filler-at-all.md

Two PRs add two different files, so there is nothing to merge. It is the same reason changesets keeps one file per change instead of one shared changelog.

396 entries moved across core, indexer, sdk and simplex. The prose is untouched. The only edit is each entry's headings moving up one level, from ## to #, since an entry is now a document rather than a section.

.gitattributes is deleted — it had nothing left to declare. The root CLAUDE.md documents the layout and says not to gather entries back into a shared file, with the GitHub reason attached so nobody re-litigates it. Each package gained a docs/ai/README.md carrying the conventions that used to sit in the three preambles.

Flows stay one file per flow and are still edited in place, so two PRs revising the same flow still conflict. That one is worth seeing: it means two changes disagree about how the code runs.

Verification

The splitter is fence-aware. That mattered — the ## YYYY-MM-DD line inside each preamble's format example would otherwise have become a bogus entry.

Every entry was then reconstructed from the files on disk: demote the headings back a level, compare to the source text in the parent commit, byte for byte. All 396 recovered, and the per-directory file counts match exactly, so no two entries slugged to the same name and quietly overwrote each other.

Two branches off this commit, each adding a changelog entry, merge with no conflict.

For open PRs

#1250, #1246, #1234 and #1185 still append to the old files, so each hits a modify/delete conflict once. Resolving it means moving the entry into a new file under changelog/ or decisions/.

The three shared files per package — ChangeLog.md, Decisions.md, Flow.md — were
append-only with newest entries on top, so any two concurrent PRs wrote the same
line and GitHub marked both conflicted.

#1251 declared `merge=union` for the two log files. That does resolve the
collision locally, but GitHub ignores merge drivers when it computes a PR's
mergeability, so the PRs stayed blocked regardless. Measured on #1250, whose
merge base is the .gitattributes commit itself and which changes nothing but
those two logs and one test: it merges into main clean locally with the union
driver, conflicts locally without it, and GitHub reports `mergeable: false`
either way.

So stop sharing the files. Each entry is now its own file under
docs/ai/{changelog,decisions,flows}/, named by date and title. Two PRs add two
different files and there is nothing to merge — the same reason changesets keeps
one file per change instead of one shared changelog. .gitattributes goes with it,
having nothing left to declare.

396 entries moved across the four packages. The prose is untouched; the only edit
is each entry's headings moving up one level, from `##` to `#`, since every entry
is now a document rather than a section. Verified by demoting every new file back
a level and comparing it to the source text it came from, byte for byte.

Flows stay one file per flow and are still edited in place, so two PRs revising
the same flow still conflict. That one is worth seeing: it means two changes
disagree about how the code runs.

Open PRs that append to the old files will hit a modify/delete conflict once.
Resolving it is moving the entry into a new file.
@seunlanlege
seunlanlege merged commit 74fa39b into main Sep 10, 2026
3 checks passed
@seunlanlege
seunlanlege deleted the docs-ai-one-file-per-entry branch September 10, 2026 11:56
seunlanlege added a commit that referenced this pull request Sep 10, 2026
…ayout

#1253 split docs/ai into a file per entry so concurrent PRs stop conflicting on
one shared file — which this branch had been doing on every rebase. Rewrites this
branch's entries into that layout: two changelog files, seven decisions, the log
flow, and the routes flow updated for /logs and its handheld gate.
seunlanlege added a commit that referenced this pull request Sep 10, 2026
…ayout

#1253 split docs/ai into a file per entry so concurrent PRs stop conflicting on
one shared file — which this branch had been doing on every rebase. Rewrites this
branch's entries into that layout: two changelog files, seven decisions, the log
flow, and the routes flow updated for /logs and its handheld gate.
seunlanlege added a commit that referenced this pull request Sep 10, 2026
…ayout

#1253 split docs/ai into a file per entry so concurrent PRs stop conflicting on
one shared file — which this branch had been doing on every rebase. Rewrites this
branch's entries into that layout: two changelog files, seven decisions, the log
flow, and the routes flow updated for /logs and its handheld gate.
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.

1 participant