Repository navigation
docs: record the architecture decisions in docs/adr - #7
Merged
Merged
Conversation
One file per decision, 35 records: the invariants of CLAUDE.md, the choices the code does not explain (materialized conditional taxons owning their links, counted filter subqueries, media zones, the search form takeover, the condition preview) and what was kept as it is on purpose (random display modes, translation key namespaces, option conditions on translated values). The records hold the decisions and their reasons only; CLAUDE.md keeps every rule in full and links its record. The README, the docs index, the overview, CONTRIBUTING and the pull request template point to them, and the public contract says that a record promises nothing.
Drop the three records about the project's own tooling (changelog, CI organisation, contributor stack): they are not decisions about the plugin a shop installs. Correct the records where the code says otherwise (fixtures skip validation, only attribute and option filters are subqueries, the preview skips rows the synchronization fails closed on, only a new icon is checked, ...). Bring the pages in line: the released migration is never edited, syncTaxon() takes no locale, the preview orders by id, the visibility runtime caches channel membership. The conditional taxons page and the code map keep the facts and link the records for the reasons. Fix stale code comments and drop the ones that only restate the code.
The upstream workaround record now states the plugin's choice (its requirements stay open) without the project's tests and CI; the icon record no longer describes the unit test that enforces it, and the bundle record no longer compares with other plugins.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this pull request does
Adds architecture decision records in
docs/adr/: one file per decision, 32 records, with an index. Each record holds a decision about the plugin and its reasons (Status, Date, Context, Decision, Consequences, Related), without paths nor figures, which stay in the pages that follow the code.CLAUDE.md, the choices the code does not explain (materialized conditional taxons owning their links, counted filter subqueries with caps, media zones replacing the native Images section, the search form takeover, the condition preview) and what is kept as it is on purpose (random display modes, translation key namespaces, option conditions on translated values).CLAUDE.mdkeeps every rule in full and links its record. The README, the docs index, the architecture overview, the code map, the conditional taxons page,CONTRIBUTING.mdand the pull request template point to the records; the public contract says a record promises nothing.migrations.md,CONTRIBUTING.md),syncTaxon()takes no locale, the preview orders by id, the visibility runtime caches channel membership. Stale code comments are fixed and comments that only restate the code are removed (comments only, no behaviour change).Points to watch
vendor/bin/phpunitlocally; Behat left to the CI, no template nor behaviour change)sh tests/check-schema-drift.shprints nothing (MySQL or PostgreSQL)UPGRADE.mdis up to date if the public contract changes (traits and interfaces, Twig hooks and functions, grid query)docs/adr/No schema nor public contract change; documentation and comments only, no release needed.