feat(docs): rework policy UX — dedicated policy-in-force page, fix landing buttons#10
Merged
danielmeppiel merged 2 commits intomainfrom May 8, 2026
Merged
feat(docs): rework policy UX — dedicated policy-in-force page, fix landing buttons#10danielmeppiel merged 2 commits intomainfrom
danielmeppiel merged 2 commits intomainfrom
Conversation
…nding buttons
- Fix splash hero buttons: links now include the /zava-agent-config base
prefix so 'Browse the catalog' and 'Quick start' actually navigate.
- Stop blasting the same yellow PolicyBanner on every page. Replace it with
a single subtle 'Governed by APM policy →' chip on the landing page that
links to the dedicated policy page. Banner removed from quick-start,
catalog index, all 7 plugin pages, and consumption-patterns.
- New 'Policy in force at Zava' page (/governance/policy/) that answers
'so what?' for developers:
* PolicyAtAGlance hero card — name, version, enforcement mode, source
* PolicyImpactTable — every clause translated into 'what this means
for you' with severity tags (block/warn/info)
* Allowed sources, blocked packages, MCP allowlist (live from policy)
* 'Will this work?' scenario table — concrete examples
* Verify-locally section with 'apm audit --ci'
* Exception request flow with pre-filled GitHub issue template URL,
triage SLA, and one-shot escape hatch
* Links to upstream APM policy reference + raw policy file
* Collapsed full YAML at the bottom for reference
- src/data/policy.ts loads DevExpGbb/.github/apm-policy.yml at build time
via raw.githubusercontent.com, with a vendored snapshot fallback so
offline dev builds keep working. Derives POLICY_IMPACTS from the live
YAML so the page tracks the real policy.
- deploy-pages workflow gains a daily cron so policy edits in the org
.github repo (which don't trigger this repo's path filter) still
propagate to the site within 24h.
- Sidebar entry renamed 'Policy & CI' -> 'Policy in force'.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
zava-agent-config publishes secure-baseline. The org policy in
DevExpGbb/.github/apm-policy.yml v2.0.0 lists secure-baseline under
required_packages, which would force this repo to pin itself — a
circular dependency by design.
Run apm audit --ci with --no-policy so the publisher still validates
supply-chain drift on its own apm.lock.yaml without being held to a
floor it can never satisfy. Consumers continue to get full org-policy
enforcement via the reusable apm-audit.yml workflow.
Companion org governance change (separate, applied via API):
- Org ruleset 'Zava platform — APM governance' narrowed to
zava-storefront (consumer rules don't apply to the publisher).
- New org ruleset 'Zava platform — marketplace publisher' covers
zava-agent-config with PR + CODEOWNERS + self-audit as required
check (the appropriate governance for a publisher repo).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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.
What
Reworks the IDP policy experience and fixes the broken landing-page buttons.
1. Fix splash hero buttons
Browse the catalogandQuick startwere 404'ing because the hrefs were missing the/zava-agent-configbase prefix. Fixed.2. Stop banner-blasting every page
Old design: a loud yellow
PolicyBanneron the landing page, quick-start, catalog index, all 7 plugin pages, and the consumption-patterns page — same copy every time, doesn't answer "so what?".New design:
PolicyChip("Governed by APM policy →") that links to the policy page.3. New "Policy in force at Zava" page
A real IDP policy page that answers what the policy actually means for developers. It's rendered from the live policy file at every build (with a vendored snapshot fallback for offline dev), so it tracks reality.
Sections:
apm-policy.ymltranslated into "what this means for you" with severity tags (block / warn / info), generated from the YAML.add microsoft/foo,drop secure-baseline,hand-edit .github/agents/, etc.) and the exact CI outcome for each.apm audit --cisnippet.DevExpGbb/.githubwith a checklist of rule, justification, scope, and mitigations. Plus a documented triage SLA and a one-shot escape hatch (apm install --no-policy).4. Daily cron rebuild
The org policy lives in
DevExpGbb/.github, which is outside this repo's path-filter for the deploy workflow. Added a daily cron so policy edits propagate to the site within 24h even when this repo hasn't changed.Files
docs/src/data/policy.ts— build-time loader (fetch→ snapshot fallback) + derivedPOLICY_IMPACTSarray.docs/src/data/policy-snapshot.yml— last-known-good copy.docs/src/components/PolicyChip.astro,PolicyAtAGlance.astro,PolicyImpactTable.astro— new.docs/src/components/PolicyBanner.astro— deleted.docs/src/content/docs/governance/policy.mdx— rewritten.docs/src/content/docs/index.mdx— buttons + chip.docs/src/content/docs/{quick-start,catalog/index,catalog/*,governance/consumption-patterns}.mdx— banner removed.docs/astro.config.mjs— sidebar label rename..github/workflows/deploy-pages.yml— daily cron added.Verified
npm run build→ 25 pages, green./zava-agent-config/catalog/and/zava-agent-config/quick-start/.devexpgbb-org-policy v2.0.0,enforcement: block).https://github.com/DevExpGbb/.github/issues/new?labels=apm-policy-exception&...with the full pre-filled body.Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com