Skip to content

docs(pages): prepare manual hosting, public API and alternatives for 0.6.0 (#48) - #89

Merged
agustin18 merged 16 commits into
stablefrom
docs/48-pages-and-060-competitive-guide
Nov 21, 2026
Merged

agustin18 merged 16 commits into
stablefrom
docs/48-pages-and-060-competitive-guide

Conversation

@agustin18

@agustin18 agustin18 commented Nov 21, 2026 •

Copy link
Copy Markdown
Owner

Goal

Prepare a public documentation experience as usable as our existing fastapi-stream-lease site and competitive with the navigation of FastAPI-CacheX, without a PyPI release or involuntary website deployment.

Verified reference designs

Proposed changes

  • Add site_url for the intended GitHub Pages address (https://agustin18.github.io/fastapi-cache/) and expand navigation with published 0.5.0 API reference and an evidence-bounded alternatives/fit comparison.
  • Add manual-only .github/workflows/docs-pages.yml, modeled on fastapi-stream-lease's Pages pipeline, using pinned Zensical and the existing fail-closed link/anchor checker. No push trigger: a merge alone will not deploy.
  • Add docs/HOSTING_AND_VERSIONING.md: source-of-truth procedure to enable Pages via Actions, manually trigger, verify real URL, mobile navigation, search, PyPI links, and only then advertise the site.
  • Explain historical docs strategy before 0.6.0. Zensical's mike integration is transitional; do not claim to offer immutable versioned pages until a tagged-source snapshot and version navigation work end-to-end.
  • Update ROADMAP and docs contributors' reference. Changelog docs fragment 86.doc.md.

Approval / acceptance

  • Full documentation site build and all local links/HTML fragments pass on exact head.
  • CI/CodeQL/Towncrier and markup/URLs review pass.
  • Review API-reference signatures against the published v0.5.0 tag, not new 0.6.0 source.
  • Independent security review: Pages token scoped, no PR secret exposure, deploy only from reviewed stable, backend/PyPI runtime untouched.
  • Separate maintainer decision to merge this PR, enable Pages settings and manually trigger a deployment; verify actual hosted URL before README/PyPI announcements.
  • docs: build versioned documentation site after PR #52 quickstart #48 remains open until hosted URL, search/mobility and version strategy are evidenced.

Do not publish a website, modify PyPI version or tag in this PR. Refs #48 #86 #88.

Security hardening added in follow-up commits (2026-11-21)

  • Workflow-level token permissions default to none; build gets contents: read only and checkout does not persist credentials.
  • Pages/OIDC write tokens are restricted to the deploy job; actions/configure-pages runs at that deploy-only permission boundary.
  • Both build and deploy jobs are gated on github.ref == 'refs/heads/stable'; workflow stays dispatch-only (no push trigger).
  • A dedicated regression test covers manual-only triggering, job permissions, stable guards, and the runbook's external policy.
  • Still required in GitHub Settings, not satisfiable through code alone: restrict the github-pages environment to deployments from stable only. Reviewers/branch policy must be configured before the first manual deploy. A changed workflow on another branch could bypass YAML-only guards.

These changes are committed to this draft, but no Pages environment setting or deployment has been changed, and fresh CI/security checks on the final HEAD remain required.

@agustin18
agustin18 marked this pull request as ready for review November 21, 2026 05:31
@agustin18
agustin18 merged commit b118890 into stable Nov 21, 2026
33 checks passed
agustin18 added a commit that referenced this pull request Nov 21, 2026
Merge #89 and #90 without overwriting the #54 bounded backend/test/CI files. Keep draft pending an independent heap/concurrency audit.
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