Generate the terms page from TERMS.md, and preserve existing anchors - #9
Merged
Merged
Conversation
Extends the privacy sync to terms/index.html, and fixes an anchor problem the first version of the renderer would have caused. Anchors are a published interface: the site's own cross-links and any external link point at them. The hand-written pages used short ids (`acceptance`, `warranties`, `third-party`) that a slug of the full heading does not reproduce, so generating blind would have broken 9 of the terms page's 13 anchors, and had already changed `changes` to `changes-to-this-policy` on the privacy page. The renderer now reads the ids off the page before replacing it and reuses the one an unchanged heading already has. No mapping file to maintain, and a heading whose text genuinely changed still gets a fresh slug, which is correct because it is a different section. Result: terms keeps all 13 anchors, and privacy now loses only `cloud-backup`, whose section was genuinely restructured into "Backup and Sync" and "Photo and Video Upload" by the policy rewrite. Terms had drifted too, less visibly than privacy: TERMS.md says "Terms of Use" throughout where this page said "Terms of Service". The generated body now follows the source. Note that the page's hand-written title, the nav and the footer still say "Terms of Service", so those two now disagree; which way to resolve it is a naming decision, not a sync one, and is left alone here. The sync workflow renders both pages and commits them together, so two renders cannot race each other pushing to the same branch.
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.
Summary
Follow-up to #8. Extends the sync to
terms/index.html, and fixes an anchorproblem the renderer in #8 would have caused.
The anchor bug, which is the important part
Anchors are a published interface: the site's own cross-links and any external
link point at them. The hand-written pages used short ids (
acceptance,warranties,third-party) that a slug of the full heading does notreproduce.
Generating the terms page blind would have broken 9 of its 13 anchors, and
#8 had already changed
changestochanges-to-this-policyon the privacypage without anyone noticing.
The renderer now reads the ids off the page before replacing it and reuses the
one an unchanged heading already has. No mapping file to maintain, and a
heading whose text genuinely changed still gets a fresh slug, which is correct
because it is a different section.
Anchor sets diffed against
origin/main:cloud-backuponlycloud-backupis a genuine loss rather than a regression: the policy rewriterestructured that section into "Backup and Sync" and "Photo and Video Upload".
A link to
#cloud-backupstill lands on the page, just unscrolled.Terms had drifted too
Less visibly than privacy.
TERMS.mdsays "Terms of Use" throughout where thispage said "Terms of Service". Otherwise the two agree: comparing the body text
against the old page gives 99.4% identity, and every difference is that one
wording change coming from the source.
Workflow
Renders both pages and commits them together, so two renders cannot race each
other pushing to the same branch. The
--checkjob on pull requests now coversboth pages and reports each failure against its own file.
Verification
--checkclean afterwardscommits
(privacy 14 headings / 3 tables / 30 items, terms 13 headings / 11 items)
One thing to decide, not changed here
The terms body now says "Terms of Use", following the source, while the page's
hand-written title, the nav links and the footer still say "Terms of Service".
Those now disagree. Resolving it is a naming decision rather than a sync one:
either rename the site chrome to match the source, or change
TERMS.md.