Open Source Update Strategy | Phase 2 | Document release subscription paths

[giverm]

User story

As a state implementer running an OSCER deployment, I want documented subscription paths to OSCER releases so that I can opt into release notifications using GitHub's built-in mechanisms without having to discover them on my own — and so that I know where breaking-change and security-patch information will surface.

Context

Once #531 establishes tagged releases, GitHub exposes the Releases page on template-strata-oscer-app as a canonical, auto-updated source-of-truth at no Nava-side cost. Implementers can subscribe via GitHub's "Watch → Custom → Releases" UI and receive notifications through GitHub's standard channels (web, email, mobile push). The mechanism is mature, well-understood, and zero-infrastructure.

The Nava precedent supports treating this as sufficient for v1: navapbc/template-application-rails has shipped tagged releases for over a year (v0.4.0 in March 2025 through v1.0.0 in May 2026) with no notification infrastructure beyond GitHub Releases — no Discussions, no announce-on-release workflow, no mailing list, no repository_dispatch fan-out. There is no documented case where this baseline has failed an implementer.

This ticket therefore scopes narrowly to documenting the subscription path rather than building a notification system. The strategy doc's broader notification surface — Channel 2 broadcast venues, automated announcement workflow, cross-repo dispatch — is deferred to follow-up tickets gated on actual implementer demand. The decision is YAGNI-aligned: GitHub's built-in mechanisms cover the use case today; speculative infrastructure is filed as future work, not built now.

Strategy detail: #213 Section 3 (Notification channels) + Section 7 Phase 2.

Effort estimate: ~0.5 day. Doc edits in two locations + a verification pass on a sample release from #531 to confirm it renders readably in GitHub's notification surfaces.

Prerequisites

• Open Source Update Strategy | Phase 1 | Create first tagged release #531 (first tagged release) — hard prerequisite. There has to be at least one tagged release for the verification pass to validate against, and Open Source Update Strategy | Phase 1 | Create first tagged release #531's release-notes structure (categories, label-to-section mapping) is what this ticket points implementers at.
• Open Source Update Strategy | Phase 1 | Author CUSTOMIZATION.md #539 (CUSTOMIZATION.md) — soft prerequisite. The "How to subscribe" section lives in CUSTOMIZATION.md and the template-repo README. If Open Source Update Strategy | Phase 1 | Author CUSTOMIZATION.md #539 hasn't landed, this ticket adds the section directly to the README and cross-links from CUSTOMIZATION.md when it lands.

Sequencing

Independent of other Phase 2 work; can be done in parallel.

Scope

In this ticket:

• "How to subscribe to releases" section in CUSTOMIZATION.md (Open Source Update Strategy | Phase 1 | Author CUSTOMIZATION.md #539) and the template-repo README. Documents:
  • GitHub Releases page as the canonical source-of-truth at https://github.com/navapbc/template-strata-oscer-app/releases.
  • "Watch → Custom → Releases" subscription path on the GitHub UI for email / web / mobile notifications.
  • Where breaking-vs-additive changes appear in release notes (sourced from the category structure established in Open Source Update Strategy | Phase 1 | Create first tagged release #531).
  • Where "required upgrade stops" guidance appears (sourced from Open Source Update Strategy | Phase 2 | Keep migrations simple and separable (audit + convention) #543's convention) when applicable to a given release.
  • Where security and policy-critical changes are flagged in release notes.
• Verification pass on a sample release from Open Source Update Strategy | Phase 1 | Create first tagged release #531: confirm the release renders readably in (a) the GitHub Releases page, (b) GitHub's email-notification format for repo watchers, (c) the GitHub mobile app's Releases view. If any rendering is poor, file feedback against Open Source Update Strategy | Phase 1 | Create first tagged release #531 rather than working around it in OSCER docs.

Out of this ticket:

• Additional notification methods. Anything beyond GitHub's built-in Watch + Releases is out of scope and can be added as a follow-up if demand arises.

Acceptance criteria

• CUSTOMIZATION.md (Open Source Update Strategy | Phase 1 | Author CUSTOMIZATION.md #539) and the template-repo README contain a "How to subscribe to releases" section documenting the canonical Releases page URL and the Watch-the-repo subscription path.
• The section identifies where breaking-vs-additive changes appear in release notes (per Open Source Update Strategy | Phase 1 | Create first tagged release #531's category structure) and where required-upgrade-stops surface (per Open Source Update Strategy | Phase 2 | Keep migrations simple and separable (audit + convention) #543's convention) when applicable.
• The section identifies how security-critical and policy-critical changes are flagged in release notes.
• Verification pass complete: a sample release from Open Source Update Strategy | Phase 1 | Create first tagged release #531 has been reviewed in the GitHub Releases page, in GitHub's email notification format (subscribe-and-trigger via a no-op patch tag), and in the GitHub mobile app's Releases view. Any rendering issues filed against Open Source Update Strategy | Phase 1 | Create first tagged release #531.
• Implementer-facing docs include a one-line note that additional notification methods can be added if demand arises, with a pointer to file an issue.

Part of #527.