From 16662a7881a7ece20c89017c70988e8a160c800e Mon Sep 17 00:00:00 2001
From: plebhash <plebhash@proton.me>
Date: Tue, 23 Jun 2026 19:26:10 -0300
Subject: [PATCH] formalize release and versioning policy

---
 RELEASE_POLICY.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 RELEASE_POLICY.md

diff --git a/RELEASE_POLICY.md b/RELEASE_POLICY.md
new file mode 100644
index 0000000..ce50630
--- /dev/null
+++ b/RELEASE_POLICY.md
@@ -0,0 +1,74 @@
+# Release and Versioning Policy
+
+This document defines the release rules for `bitcoin-capnp-types` so branch history, tags, GitHub releases, and `crates.io` versions stay aligned.
+
+## Scope
+
+This policy applies to:
+
+- branch release flow
+- git tags
+- GitHub releases
+- crates.io publishes
+
+## Branch Model
+
+- `master` tracks the current active development line.
+- Maintenance branches (for example `30.x`, `31.x`) track stable backport lines.
+- A release must be cut from the branch that owns that version line.
+
+## Version Line Mapping
+
+- `30.x` branch -> `0.1.x`
+- `31.x` branch -> `0.2.x`
+- Future Bitcoin Core branch lines should get a new crate minor line (`0.N.x`).
+
+## Required Invariants
+
+For every released version `X.Y.Z`, all of the following must exist and match:
+
+1. `Cargo.toml` version is `X.Y.Z` on the release commit.
+2. Git tag `vX.Y.Z` points to that exact commit.
+3. Tag `vX.Y.Z` is reachable from the intended release branch.
+4. A GitHub release exists for `vX.Y.Z`.
+5. A crates.io release exists for `X.Y.Z`.
+
+No detached tags and no crates publish without corresponding tag and GitHub release.
+
+## Release Checklist
+
+1. Choose release branch (`master` or maintenance branch).
+2. Update version in `Cargo.toml`.
+3. Run tests and merge the release PR.
+4. Create and push annotated tag `vX.Y.Z` on the merged commit.
+5. Publish crate `X.Y.Z` to crates.io.
+6. Create GitHub release for `vX.Y.Z`.
+7. Verify branch/tag/release parity.
+
+## Verification Commands
+
+```sh
+git tag --sort=version:refname
+git branch --contains vX.Y.Z
+gh release view vX.Y.Z
+cargo metadata --no-deps
+```
+
+Use `Cargo.toml` and crates.io UI/API to verify the published crate version if needed.
+
+## Backfill and Repair Procedure
+
+If a historical mismatch is found (missing tag, missing GitHub release, or tag not on a branch), repair immediately by:
+
+1. creating or fixing the correct tag placement,
+2. publishing missing GitHub release metadata,
+3. documenting what was corrected in the PR description.
+
+## Enforcement
+
+Any PR that bumps crate version or prepares a release should include a checklist confirming:
+
+- branch line is correct,
+- tag plan is defined,
+- GitHub release will be created,
+- crates.io publish is accounted for.