Tracking: fork-preview banner, dual Atom feeds, gh-pages deploy hardening

[netravnen]

Tracking issue for a set of docs-repo infra changes developed on a
fork (netravnen/peeringdb-docs). Originally proposed as a single
draft PR (#449), now split into two independently reviewable PRs:
#450 (content fixes) and #451 (fork-preview banner, Atom feeds,
site-URL resolution, gh-pages deploy hardening).

This repo's README asks that issues generally go to
peeringdb/peeringdb#issues -- filing here instead since this is a
tracking issue for an open PR against this repo specifically, not
a bug report or support request. A lightweight FYI is also posted at
peeringdb/peeringdb#2027 for visibility on that side.

The underlying motivation: running a dev/preview fork of this site
surfaced three problems worth fixing generally, not just working
around locally -- preview deploys are indistinguishable from
production in a browser, blog and release-notes readers only had one
combined feed to subscribe to, and gh-pages accumulated deploy
history with no guarantee it matched the branch that built it.

Summary of scope (breakdown: #448 (comment)):

• A fork-preview banner (suppressed via PROD=TRUE) so non-production
  deploys of this site are never mistaken for docs.peeringdb.com.
• Independent Atom feeds for the blog and for release notes
  (docs/blog/atom.xml, docs/release_notes/atom.xml), plus a shared
  site-URL resolution policy used across the banner, both feeds, and
  dynamic CNAME generation.
• mkdocs gh-deploy --no-history, so the gh-pages branch is always
  a single fresh commit rather than accumulating deploy history.

See #450 and #451 for the full commit-by-commit breakdown and open
questions for reviewers.

[netravnen]

I run a public dev preview of this work at
https://docs-dev.peeringdb.dk. The fork-preview banner and both Atom
feeds can be checked live there rather than only from local builds.

[leovegoda]

@netravnen I created peeringdb/peeringdb#2026 after this month's @peeringdb/pc meeting where we agreed that the RSS/Atom feeds are a good idea. @grizz do you agree with using --no-history?

[ccaputo]

I usually deploy with --clean. What does --no-history achieve? I see it means "Replace the whole Git history with one new commit." but I don't understand what that really does or the purpose.

[netravnen]

I usually deploy with --clean. What does --no-history achieve? I see it means "Replace the whole Git history with one new commit." but I don't understand what that really does or the purpose.

--no-history: every deploy is a single fresh commit built from the current branch (master/main), instead of accumulating commits on top of whatever was already on the gh-pages branch.

Not using --no-history makes the branch history look like this (upstream/gh-pages):

    $ git -C ~/projects/private/peeringdb/docs log --oneline --graph --all -n 30

    * 2f903143 Deployed fc25e47 with MkDocs version: 1.4.3    ← origin/gh-pages
    * fc25e47d ci(deploy): force gh-pages to a single fresh commit each deploy
    * 01940f2f feat(feed): add release notes Atom feed            ↑
    * f6ebaf30 refactor(feed): extract shared atom_common helpers  │
    * f2bc0c9a feat(theme): add fork-preview banner above nav bar  │ admincom/docs-improvements
    * dcc1df3e feat(hooks): unify site-URL resolution              │ (our branch)
    * 09152752 feat(deploy): generate docs/CNAME dynamically       │
    * 7ef73bcd feat(blog): generate an Atom feed with git-derived dates
    * 500a0c01 ci(docs): add fork preview build-check and deploy workflows
    * ...
    * 3b97e2fa (upstream/master) Blog post on release post experiment
    * e1f21bdb Fixes Title Case for most recent blogpost
    * 733ec0a3 Linked to blog post on removing beta for August
    * 9bd9d681 Added Maximiliano Estudies to PC
    | * 90f1c9bd Deployed 9bd9d681 with MkDocs version: 1.4.3    ←┐
    | * e5d07b54 Deployed 733ec0a3 with MkDocs version: 1.4.3      │
    | * a0b39f6e Deployed e1f21bdb with MkDocs version: 1.4.3      │
    | * f45d94a4 Deployed 3b97e2fa with MkDocs version: 1.4.3      │ upstream/gh-pages
    | * d8aba804 Deployed 9f1ec3f3 with MkDocs version: 1.4.3      │ (no --no-history)
    | * 9abcced3 Deployed 4b3a05a0 with MkDocs version: 1.4.3      │
    | * 349d663f Deployed 5fc2b9f3 with MkDocs version: 1.4.3      │
    | * 16ae93c1 Deployed cfbe722c with MkDocs version: 1.4.3      │
    | * ...                                                        │
    | * ...                                                        │

Using --no-history makes every commit commit to gh-pages be a single commit on top of the latest commit on the master/main branch it was based on (origin/gh-pages):

    $ git -C ~/projects/private/peeringdb/docs log --oneline --graph --all -n 30

    * 2f903143 Deployed fc25e47 with MkDocs version: 1.4.3    ← origin/gh-pages
    * fc25e47d ci(deploy): force gh-pages to a single fresh commit each deploy
    * 01940f2f feat(feed): add release notes Atom feed            ↑
    * f6ebaf30 refactor(feed): extract shared atom_common helpers  │
    * f2bc0c9a feat(theme): add fork-preview banner above nav bar  │ admincom/docs-improvements
    * dcc1df3e feat(hooks): unify site-URL resolution              │ (our branch)
    * ...                                                          │
    * ...                                                          │

Running git log --oneline --graph --all -n 500 locally in the cloned repo presents the ASCII graph a bit more cleanly.

[netravnen]

https://github.com/peeringdb/docs/pull/449/changes

Atom Feeds (examples):

• Release notes: https://docs-dev.peeringdb.dk/release_notes/atom.xml
• Blogs: https://docs-dev.peeringdb.dk/blog/atom.xml

Published default to the commit time of the tracked object in the git history.

Written as "raw" py scripts, avoid dependencies. Only ATOM feeds are generated, skip duplicate feeds URL's by not including the older RSS standard. Only the newer ATOM standard.

Release Notes and Blog gets their own independent feeds instead of an aggregated one. Such that the user(s) can choose what to subscribe to.

DeskPro Snippets:

• https://docs-dev.peeringdb.dk/committee/admin/deskpro_snippets/

A list of all the DeskPro snippets used by the AC.

MkDocs:

• The suggested github actions flows automatically build the new deployment upon push/merge to master/main branch. Skipping the requirement for a manual deployment to the gh-pages branch.
• PROD=TRUE (gh variable; enforce prod CNAME) -> Else SITE_URL_OVERRIDE (gh variable) -> gh repo URL -> Else localhost:<port>

Docs:

• Update the "getting started as X" documents with the requirements we list in the DeskPro snippets and the applied acceptance criteria. Aligns docs and AC DeskPro responses.
  • IX: Min 3x peers
  • Carrier: Service requirements
  • facility: Service requirements
  • Network: Assigned ASN and RDAP validation
  • IX/FAC/Carrier deletions: Why they fail
• Add section:
  • "Mergers and Acquisitions"
  • "Why can't I delete my Facility, IX Prefix, or Point of Contact?"
• Clarify MFA/TOTP requirements
• Move:
  • "About PeeringDB" to the index.md page
  • Contents regarding API ussage to docs/howto/query_the_api.md - Mainly contents prior contained in docs/howto/search.md
  • "Tutorials and workshops" moved to docs/presentations.md
• Replace yumwith dnf

[grizz]

Nice, looks good, thanks!

--no-history is fine