From 803fbfdd9f359158e247d9d1950c7d6f4605844a Mon Sep 17 00:00:00 2001
From: Michel Roegl-Brunner <michel.roegl-brunner@htl-braunau.at>
Date: Mon, 24 Aug 2026 13:14:17 +0200
Subject: [PATCH] Document the breaking-change advisory block in the PR
 template
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Explains the ```breaking-change block a breaking-change PR can carry —
severity, action (warn/block), expect, and before_update steps — with a
copy-paste example kept inside an HTML comment so it stays inert until an
author fills it in.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TFBuZEp142Ei2PAfWqbMXT
---
 .github/pull_request_template.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index ecffc788e..5c83104b2 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -35,3 +35,35 @@ Fixes #
 - [ ] 🌍 **Website update** – Changes to script metadata (PocketBase/website data).
 - [ ] 🔧 **Refactoring / Code Cleanup** – Improves readability or maintainability without changing functionality.
 - [ ] 📝 **Documentation update** – Changes to `README`, `AppName.md`, `CONTRIBUTING.md`, or other docs.
+
+---
+
+## 💥 Breaking Change Advisory (only if you checked "Breaking change")
+
+If this PR changes existing behaviour in a way that may require action before an
+update, add a `breaking-change` advisory block to this PR body. The website and
+the in-container update guard read it to tell operators exactly what to expect,
+what to do first, and — with `action: block` — to stop an update until it's
+handled. Every field is optional; the advisory auto-expires 30 days after merge.
+
+Copy the block out of the comment below, fill it in, and paste it here:
+
+<!--
+```breaking-change
+severity: warning        # info | warning | critical
+action: warn             # warn (default) | block — "block" halts the update until an operator forces it
+expect: One line describing what changes and why it may need action.
+before_update:
+  - First thing to do before updating
+  - Second thing to do before updating
+```
+
+Guidance:
+- Leave this commented (or delete it) for a routine change — no block, no advisory.
+- Use `action: block` only for changes that break or lose data if the operator
+  updates without acting first (e.g. a required manual migration or backup).
+- `expect:` supersedes the auto-scraped summary; keep it to one line.
+- Steps render as a checklist on the site and in the update prompt.
+-->
+
+<!-- The advisory block is only active once it is OUTSIDE this comment. -->