docs: put the template-authoring guides on the packages that exist - #483
Merged
Conversation
A contributor following the authoring guide wrote code that does not compile. It described a family as `templates.<family>.v2` with exactly five sub-packages, one of them a per-family `theme/`; 2.0 dropped the `.v2` level and moved the tokens into the shared `templates.core.theme`, leaving four. The contributing guide routed the same work into `templates.builtins` and `templates.support`, neither of which has held a file since the split, and still listed the weekly schedule among the built-in templates although its document is composed by an example. Package names join the retired-surface guard. It could only match types, which is why two dead package names sat in the document that sends every new contributor to them. Also: the extension guide pointed at a snapshot-test directory that is not in the repository, the layout-snapshot page listed two tests among six that are not either, the docs index carried a rework warning for a page reworked in 2.0, and the roadmap asked for a warning on dropped DOCX content that the backend already emits — the part still missing is a mode that refuses instead of dropping, which is what it now asks for.
The guide was fixed and the pages around it were not, so the folder's own landing page still described `<name>/v2/data` with a per-family `theme/` box, and the contributing guide contradicted itself a hundred lines below the paragraph that had just been rewritten. A reader routed from the docs index lands on the landing page first. The four-sub-package claim was also wrong in the other direction: only `presets/` is always there. CV carries all four, cover letter has no `widgets/`, and invoice and proposal are presets alone over records in the shared `templates.data.<family>` — which made the worked walkthrough, built around invoice, describe directories that are not on disk. It now presents the fullest shape and says which families take less. Three leftovers in the same file: a required test for a `<Family>Theme` the guide forbids two sections earlier, and two pointers into `core/` for a parity test and its baselines that moved to `qa` in the module split. The preset cookbook had the third. The retired-package tokens now cover the path spelling as well as the dotted one — the sentence that carried a dead package for a release wrote it as a path.
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
1 participant
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.
Why
A contributor who followed the authoring guide wrote code that does not compile.
docs/templates/v2-layered/contributor-guide.mddescribes a family as living undertemplates.<family>.v2in "exactly five sub-packages", one of them a per-familytheme/with anInvoiceTheme(palette, typography, spacing, decoration)aggregate. On 2.x there is no.v2level, a family has four sub-packages (data/components/widgets/presets, and the cover-letter family has nowidgetsat all), and the tokens are the sharedBrandThemeintemplates.core.theme. The guide also forbids editing "the v1 surface" for the same family, a surface that no longer exists.docs/README.md:21routes every new-template contributor here.CONTRIBUTING.mdrouted the same work intotemplates.builtinsandtemplates.support. Neither package has held a file since the 2.0 split. It also listed the weekly schedule among the built-in templates; its data records ship, but the document is composed by an example, not by a template.Three more documents point at things that are not in the repository, and the roadmap asks for something half-shipped.
What
The authoring guide matches the tree. Package path, sub-package list, the layer contract table, the worked invoice walkthrough, both checklists and the "must not do" list. The step that used to have the contributor write a family theme record now says there is nothing to write, and says why the tokens are shared — a private palette is how visual consistency is lost one family at a time.
The contributing guide names the real packages and stops claiming a schedule template.
Package names join
RETIRED_IN_2_0_TOKENS. The guard could only match type names, which is exactly why two dead package names survived in the document that sends every new contributor to them.templates.builtinsandtemplates.supportare now caught inCONTRIBUTING.md,docs/**and.github/**.Dead pointers removed. The extension guide sent readers to
core/src/test/.../templates/builtins/andBuiltInTemplateLayoutSnapshotTest; neither exists, and the same class name was quoted in an example's Javadoc. The layout-snapshot page listedRepositoryShowcaseRenderTestandTablePaginationIntegrationTestamong six examples — the other four exist, those two do not. The docs index still warned thatbusiness-templates.mdwas "being reworked" for the layered surface; that rework landed in 2.0.The roadmap asks for the half that is missing. Dropping a node DOCX cannot carry already warns (
DocxSemanticBackendlogs it); the entry now asks for the strict mode that refuses instead of dropping.Nothing here touches the root README,
assets/readme/, the release pipeline or CodeQL.Tests
Core guard job as CI runs it: 37 tests,
BUILD SUCCESS.qagate: 688 tests,BUILD SUCCESS.examplescompiles.templates.builtinsback inCONTRIBUTING.mdtemplates.supportback in the authoring guide