The PMP resource key is the file name in the tag's URL - #240
jwrosewell wants to merge 4 commits into
Conversation
The loader is served at /api/v4/pmp/{resource}.js and each bundle at
/api/v4/pmp/{resource}/{name}, so the key is a path segment, the same
shape as every other keyed request, and data-resource-key is gone.
Both tag snippets, the attribute table and the load sequence diagram
follow. The integration page says plainly what the old shape was and that
it is answered 404 now, because a reader arriving with a working page
from an earlier release needs to know why it stopped rather than be left
to guess.
101 uses across eight pages, against the rule that PMP is the name and "the platform" is not, which matters most here because these pages also talk about a consent management platform and the reader has to be able to tell which one a sentence means. What stays. "Consent management platform" and "Preference Management Platform" are untouched, being the full names. So is every "your platform", "whose platform" and "that platform" in the consent management platform page, because those mean the reader's own platform and not this one. So is the console message quoted there, because the client script really writes those words and the documentation has to match. One line in that page said "the platform itself may load later" about the reader's consent management platform, which now names it, because a sentence that could be read either way is exactly what this rule is for.
… card wait starts as the PMP now does, and name the PMP, the Global Privacy Platform and the consent management platform where each is meant
The preview clones every API repo at the pull request's base branch, so a
documentation change can be previewed against the API change it describes.
Where the repo has no branch of that name the clone fails outright and the
whole preview fails with it.
That happens every time a documentation branch is raised against another
documentation branch, because the base name is then a documentation branch
name and it means nothing in an API repo. The preview reports
fatal: Remote branch <name> not found in upstream origin
and stops at the first repo in the map, so none of the documentation is
built and the failure says nothing about the documentation itself.
Each repo is now asked whether it has the branch, with git ls-remote, and
cloned at main where it does not. A repo that does have it is still cloned
at it, which is the behaviour the preview is there for, and an examples
repo is asked separately from the repo it sits inside because the two can
differ. The chosen ref is printed for each, so a preview that built against
main rather than a paired branch says so in its own log.
git ls-remote exits zero with no output for a branch that is not there, so
the emptiness of the output is the test rather than the exit code, which
leaves a genuinely unreachable repo still failing the run.
The Preview failure was the preview script, not this documentationWhat failed
Why
$ref = $env:GITHUB_BASE_REF ? $env:GITHUB_BASE_REF : $env:GITHUB_REF_NAME ? $env:GITHUB_REF_NAME : 'main'
...
git clone -b $ref --depth=1 ... "https://github.com/$owner/$repo.git" "$apis/$repo"That works while the base branch is Any documentation branch raised on another documentation branch hits this, The fix
function Resolve-Ref($url, $preferred) {
if ($preferred -eq 'main') {
return 'main'
}
$found = git ls-remote --heads $url $preferred
return $found ? $preferred : 'main'
}Three things worth noting about it. A repository that does have the branch is still cloned at it, so the paired The chosen ref is printed for each repository, so a preview that built VerifiedChecked against the real remotes before committing. An absent branch resolves In CI, run Both checks on this pull request are now green. OutstandingThe fix is a CI change sitting on a documentation branch, which is untidy. It |
1 participant
The Preference Management Platform reads its resource key from the URL path
and from nowhere else, so the pages that document it have to say so.
Stacked on
feature/create-last-g.What the pages now say
api/v4/pmpapi/v4/pmp/{resource}.jsapi/v4/pmp/{name}api/v4/pmp/{resource}/{name}data-resource-keyThat is the shape
api/v4/{resource}.jsandapi/v4/{resource}.jsonalready take, so the PMP now reads like every other keyed endpoint.
Both tag snippets on the integration page, the complete tag and the
attribute table on the configuration page, and the load sequence diagram on
the index page all follow.
data-resource-keyis gone from the attributetable, because it is not an attribute any more.
The integration page says plainly what the old shape was and that it is
answered 404 now. A reader arriving with a page that worked on an earlier
release needs to know why it stopped rather than be left to guess, and the
reason is worth stating, which is that two places to write one key meant a
page could carry one the service never saw and the refusal that followed was
invisible to the page.
Second commit, the naming
101 uses of "the platform" across eight pages become "the PMP". PMP is the
name, and it matters most here because these pages also talk about a consent
management platform, so a reader has to be able to tell which one a sentence
means.
What stays untouched:
being the full names.
consent management platform page, because those mean the reader's own
platform and not this one.
writes those words and the documentation has to match what a reader will
see in their console.
One sentence on that page said "the platform itself may load later" about
the reader's own consent management platform. It names it now, because a
sentence that could be read either way is exactly what the naming rule is
for.
Four of the 101 were invisible to a plain search, because the two words sat
on separate lines. The files use CRLF line endings, so a multiline pattern
written with
\nmatches nothing and reports the page clean.Checked
@reftarget in this repository is a@pagelabel rather thanheading text, so renaming the five headings that said "the Platform"
breaks no link.
.utm-lint.jsonis{ "mode": "forbid" }and nothinghere adds a tagged link.
Has to move with it
The service change that makes this true, and the preference demo in
51Degrees/device-detection-dotnet-exampleson branchfeature/pmp-key-in-path, whose fourteen page templates wrote the oldshape.