Skip to content

Split FOG 1.5 and 1.6 documentation - #160

Merged
mastacontrola merged 1 commit into
masterfrom
split-1-5-1-6-docs
Aug 31, 2026
Merged

Split FOG 1.5 and 1.6 documentation#160
mastacontrola merged 1 commit into
masterfrom
split-1-5-1-6-docs

Conversation

@mastacontrola

Copy link
Copy Markdown
Member

Summary

Adds docs/1.5/ for the 31 pages where FOG 1.5 and 1.6 genuinely differ — PKI/Secure Boot architecture, plugins, LDAP, site scoping, host CSV format, installer flags, .fogsettings keys, reports, storage nodes, and a handful of API/troubleshooting pages. The other ~90 pages that don't differ between versions stay shared, unforked.

Every forked pair cross-links to its counterpart via a top-of-page callout. A new "FOG 1.5" pill sits in the sidebar next to Installation/Management/Knowledge Base/Development.

Each 1.5 page is grounded in fogproject's dev-branch source, not just adapted from the existing docs' framing — that framing turned out to be wrong in a few places (see below).

Real findings from grounding this in source

  • 1.5's PKI architecture already has the three-zone split (Web/Client/Secure Boot CAs) — the original assumption of "1.5 has one CA" was wrong; what's actually 1.6-only is narrower (storage-node cert issuance, Setup Mode enrollment, per-zone bring-your-own-CA for Secure Boot specifically).
  • HTTPS and Secure Boot are still mutually exclusive on 1.5 — the installer skips staging the signed Secure Boot chain entirely when httpproto=https. Documented as explicit danger callouts.
  • csv_import_export.md's "new in FOG 1.6" claim was false — generic CSV import/export has existed since ~2017; what's actually new in 1.6 is header-row support, the associations column, and FK name resolution. Fixed on the 1.6 page.
  • A real bug: the 1.6 primary-mac-address-issues.md page's direct-SQL fix used set primary="1" instead of the actual column name hmPrimary — fixed on both pages.
  • A real bug: FOG 1.5's host CSV export drops the pingstatus column that import expects — documented as a warning on the 1.5 page.
  • An overstated 1.6-only claim about multicast port-pool behavior — it was actually backported to dev-branch in July 2026 — corrected.

Mechanical cleanup that came with the split

Because docs/1.5/.../<name>.md and docs/.../<name>.md now share 31 basenames, every wikilink to one of them had to be fully path-qualified — a bare [[name]] resolves through a context_id alias-redirect stub instead of the real page, which silently drops any #anchor on the link (a failure mode this repo's own CLAUDE.md already documents). Fixed site-wide, not just in the forked pages. Also converted legacy !!! mkdocs admonition syntax to Obsidian callouts in every file touched.

docs/development/version-sync-automation.md is separately rewritten — it had drifted since GH-1510/GH-1513 replaced the tracked-file FOG_VERSION stamp with a generated, gitignored packages/web/commons/version.php. Verified against the current .githooks/ scripts and the merged fog-workflows#39. Also flags that dev-branch hasn't received the generated-file port yet, so it's still on the old mechanism.

Test plan

  • npm run docs:build — clean, no broken/literal [[ wikilinks (verified against the full built HTML, not just per-batch)
  • node --test "scripts/*.test.mjs" — 51/51 pass
  • No duplicate context_ids across the site
  • Spot-check a few pages in the live preview once this deploys to Read the Docs

Co-Authored-By: Claude noreply@anthropic.com

Adds docs/1.5/ for the 31 pages where FOG 1.5 and 1.6 genuinely
diverge (PKI/Secure Boot architecture, plugins, LDAP, site scoping,
CSV format, installer flags, .fogsettings keys, and more), each
grounded in fogproject's dev-branch source rather than the existing
docs' own framing. The other ~90 pages that don't differ stay shared.

Every forked pair cross-links to its counterpart; the 1.6-side pages
keep their content but point to the 1.5 version where one exists.
Site-wide, wikilinks to the 31 now-ambiguous basenames are
path-qualified, since a bare link would otherwise resolve through a
context_id alias-redirect stub instead of the real page, silently
dropping any #anchor. Legacy `!!!` mkdocs admonition syntax was
converted to Obsidian callouts in every file touched.

Also rewrites development/version-sync-automation.md, which had
drifted since GH-1510/GH-1513 replaced the tracked-file FOG_VERSION
stamp with a generated, gitignored packages/web/commons/version.php.

Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant