docs(enterprise): refactor section IA -- hub + merge teams + dedupe governance#858
Merged
danielmeppiel merged 4 commits intomainfrom Apr 22, 2026
Merged
docs(enterprise): refactor section IA -- hub + merge teams + dedupe governance#858danielmeppiel merged 4 commits intomainfrom
danielmeppiel merged 4 commits intomainfrom
Conversation
…overnance
The Enterprise section had 4 overlapping pages (Teams, Governance Guide,
Governance & Compliance, apm-policy.yml) with duplicated narrative,
sidebar order collisions, and an unclear path through the section for
the three target personas (CISO, VP Eng, Platform Lead).
Refactor to 7 pages with no overlap:
1. Enterprise (NEW hub) -- pillar paragraph + role router + map
2. Making the Case -- problem-at-scale (was Teams) + advocacy
3. Adoption Playbook -- phased rollout
4. Security Model -- supply-chain posture
5. Governance -- bypass contract + install gate (was Guide)
6. Policy Files -- mental model (was apm-policy.yml)
7. Policy Reference -- full schema
Changes:
- Add docs/src/content/docs/enterprise/index.md (hub page)
- Merge teams.md narrative into making-the-case.md as the lead section
('The problem at scale' + 'How APM solves this'), then existing
TL;DR / talking points / objections / RFC / comparison / ROI
- Delete teams.md, governance.md (content grafted where appropriate)
- Rename governance-guide.md title 'Governance Guide' -> 'Governance';
reorder
- Rename apm-policy.md title 'apm-policy.yml' -> 'Policy Files'; reorder
- Add redirects in astro.config.mjs so /enterprise/teams and
/enterprise/governance resolve to their successors
- Graft governance.md SOC 2 / security audit / change management
scenarios into reference/lockfile-spec.md sec 9 (the lockfile-as-audit-
trail home, where they belonged all along)
- Update 4 inbound links (policy-reference, github-rulesets, ci-cd,
ci-policy-setup) from .../enterprise/governance/ to
.../enterprise/governance-guide/
Build passes, all internal links valid, 43 pages.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Refactors the Enterprise docs information architecture to remove overlapping sidebar entries by introducing an Enterprise hub page, merging/renaming pages, and preserving published URLs via redirects and link updates.
Changes:
- Adds a new
enterprise/hub page and reorders/renaps Enterprise section entries for clearer navigation. - Merges former “Teams” narrative into “Making the Case” and relocates governance/compliance scenarios into the lockfile spec.
- Deletes redundant Enterprise pages and updates inbound links + adds redirects to preserve old URLs.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/reference/lockfile-spec.md | Adds SOC2/forensics/change-management recipes under auditing patterns and links to Governance. |
| docs/src/content/docs/integrations/github-rulesets.md | Updates related-link target from removed Governance page to Governance Guide slug. |
| docs/src/content/docs/integrations/ci-cd.md | Updates governance link to Governance Guide slug. |
| docs/src/content/docs/guides/ci-policy-setup.md | Updates governance link to Governance Guide slug. |
| docs/src/content/docs/enterprise/teams.md | Deletes legacy “APM for Teams” page (content merged into Making the Case). |
| docs/src/content/docs/enterprise/security.md | Updates sidebar order metadata to reflect new IA. |
| docs/src/content/docs/enterprise/policy-reference.md | Updates sidebar order metadata and fixes related link to Governance Guide slug. |
| docs/src/content/docs/enterprise/making-the-case.md | Expands to include the “problem at scale” lead and updates positioning/links for the new Enterprise flow. |
| docs/src/content/docs/enterprise/index.md | Adds new Enterprise hub page with pillar framing, role router, and section map. |
| docs/src/content/docs/enterprise/governance.md | Deletes legacy “Governance & Compliance” page (content relocated/deduped). |
| docs/src/content/docs/enterprise/governance-guide.md | Renames page title to “Governance” and adjusts sidebar order metadata. |
| docs/src/content/docs/enterprise/apm-policy.md | Renames page title to “Policy Files” and adjusts sidebar order metadata. |
| docs/src/content/docs/enterprise/adoption-playbook.md | Adjusts sidebar order metadata to match new IA. |
| docs/astro.config.mjs | Updates Enterprise sidebar items and adds redirects for removed Enterprise routes. |
Copilot's findings
- Files reviewed: 14/14 changed files
- Comments generated: 2
Air-gapped, Artifactory-routed deployments are an enterprise control-plane concern peer to security and governance, not a guide footnote. Previously the topic was fragmented across guides/marketplaces.md (env-var summary), governance-guide §9 (policy cache), security.md (HTTP fallback), and pack-distribute.md (offline bundles), with no single page a CISO or platform lead could read end-to-end. New page: enterprise/registry-proxy.md - Two operating modes (transparent env-var, explicit FQDN) - Bypass-prevention contract: PROXY_REGISTRY_ONLY=1 + lockfile guard, with a paste-ready trust statement for procurement - Coverage matrix (what is and is not proxy-routed: install/marketplace yes; install --mcp and ADO no; policy fetch separate) - Air-gapped CI playbook in two shapes (Shape A: CI reaches proxy; Shape B: bundle delivery) - Failure modes table grounded in the actual exception messages - Auth composition (PROXY_REGISTRY_TOKEN vs GitHub PAT) Sidebar restructure (Enterprise group): inserted Registry Proxy at order 6, between Governance and Policy Files; bumped apm-policy 6->7 and policy-reference 7->8. Cross-doc rewire: - enterprise/index.md hub: added registry-proxy to role router and section map; added platform-engineer rollout row - enterprise/security.md: 'see also' pointer from HTTP deps section - enterprise/governance-guide.md §9: distinguishing paragraph (policy- cache offline vs dep-traffic offline are different mechanisms) - guides/marketplaces.md: truncated 'Registry proxy support' section from a config snippet block to a 2-line summary + link - guides/pack-distribute.md: parenthetical positioning bundles as the offline-delivery complement to the proxy's online-routing story Build: 44 pages, all internal links valid. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
danielmeppiel
added a commit
that referenced
this pull request
Apr 23, 2026
* chore: prepare v0.9.2 release Bumps version to 0.9.2 and finalizes CHANGELOG with one-line summaries for each PR merged since 0.9.1. Highlights: - ADO AAD bearer-token auth (#856) - Governance Guide + enterprise docs IA refactor (#851, #858) - Merge Gate orchestrator + single-authority aggregation (#865, #867) - Landing + first-package docs rewrite (#855, #866) - gh-aw imports migration (#864) - Custom-port surfacing fix (#804) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: simplify merge-gate to single pull_request trigger The dual-trigger pattern (pull_request + pull_request_target with concurrency cancel-in-progress) shipped in #865 was over-engineered. It produced TWO 'gate' check-runs per SHA -- one SUCCESS, one CANCELLED -- and branch protection's status-check rollup treats CANCELLED as failure, so PRs were silently BLOCKED unless an admin overrode (which masked the bug on #867). GitHub Actions has no primitive for 'either of these events succeeded'. World-class OSS projects (kubernetes, rust, deno, next.js) accept this and use a single trigger. The cost: a dropped 'pull_request' webhook (rare; observed once on PR #856) requires manual recovery. Recovery paths now documented at top of file: - push empty commit - gh workflow run merge-gate.yml -f pr_number=NNN - close + reopen PR Replaces the dual-trigger + bootstrap-fetch dance with a clean two-job flow: resolve-sha (handles workflow_dispatch input or PR head) then gate (sparse checkout + run script). Same script, same exit codes, same EXPECTED_CHECKS env. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: collapse merge-gate into a single job (one check-run in PR UI) The two-job split (resolve-sha + gate) created two visible check-runs. Inlining the SHA resolution as a step within the gate job leaves only one check-run -- 'Merge Gate / gate' -- on the PR. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- 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
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
After PR #851 (governance guide flagship) and PR #855 (docs landing three-pillar refresh) merged, the Enterprise sidebar had 4 overlapping titles that confused readers and collided on sidebar order:
APM for TeamsGovernance GuideGovernance & Complianceapm-policy.ymlA doc-writer expert reviewed the section and proposed a 7-page IA with a hub, no overlaps, a clear path for each persona, and preserved URLs for everything that was already published.
Proposal (implemented)
enterprise/enterprise/making-the-caseenterprise/adoption-playbookenterprise/securityenterprise/governance-guideenterprise/apm-policyenterprise/policy-referenceChanges
enterprise/index.md-- hub page with pillar paragraph, role router (CISO / VPE / Champion / Engineer), and section mapteams.mdproblem-at-scale narrative is now the lead ofmaking-the-case.md, followed by the existing TL;DR / talking points / objections / RFC / comparison / ROI sectionsteams.md,governance.md(content either grafted or already present elsewhere)governance-guide.md: title ""Governance Guide"" -> ""Governance""apm-policy.md: title ""apm-policy.yml"" -> ""Policy Files""governance.mdSOC 2 / security audit / change management scenarios intoreference/lockfile-spec.mdsec 9 (the lockfile-as-audit-trail home)astro.config.mjsso existing URLs still resolve:/enterprise/teams->/enterprise/making-the-case/enterprise/governance->/enterprise/governance-guidepolicy-reference.md,github-rulesets.md,ci-cd.md,ci-policy-setup.md-- all updated from../../enterprise/governance/->../../enterprise/governance-guide/Verification
cd docs && npm run build-> 43 pages, all internal links validConstraints respected
governance-guideslug preserved per prior user constraint