From 2c2761d8cbe5e1ac9440d8e5c040cabbd19534c1 Mon Sep 17 00:00:00 2001
From: Abel Luck <abel@guardianproject.info>
Date: Tue, 24 Feb 2026 16:02:12 +0100
Subject: [PATCH] add readme

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

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..45f5f63
--- /dev/null
+++ b/README.md
@@ -0,0 +1,74 @@
+# nix-matrix-pkgs
+
+[![Update Pins](https://guardianproject.dev/ops/nix-matrix-pkgs/badges/workflows/update.yml/badge.svg)](https://guardianproject.dev/ops/nix-matrix-pkgs/actions)
+
+Pinned Nix packages for the Matrix ecosystem, providing multiple versions simultaneously so sites can upgrade independently.
+
+Canonical Repository: https://guardianproject.dev/ops/nix-matrix-pkgs
+
+## Overview
+
+When running multiple Matrix deployments, each site needs to control exactly when it upgrades. Bumping a shared nixpkgs input upgrades every site at once, which is unacceptable for production services that require coordinated, intentional upgrades.
+
+This repository maintains one standalone Nix flake per package version, each pinning nixpkgs to the revision where that version was current. A site picks a version by referencing the corresponding flake. Upgrading is an explicit change to the flake input, nothing more.
+
+Currently tracked packages:
+
+- matrix-synapse
+
+The set of available versions is controlled by `rules.nix`, which declares how many recent versions to keep and any extra versions to pin per package. A CI workflow runs daily and on changes to `rules.nix`, automatically discovering new releases from nixpkgs-unstable and creating or removing version directories as needed.
+
+## Usage
+
+Reference a specific version directory as a flake input using `?dir=`:
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
+
+    matrix-synapse-pinned.url = "git+https://guardianproject.dev/ops/nix-matrix-pkgs?dir=matrix-synapse@1.146.0";
+    matrix-synapse-pinned.inputs.nixpkgs.follows = "";
+  };
+
+  outputs = { nixpkgs, matrix-synapse-pinned, ... }: {
+    # Use the package directly
+    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
+      modules = [
+        {
+          nixpkgs.overlays = [ matrix-synapse-pinned.overlays.default ];
+        }
+      ];
+    };
+  };
+}
+```
+
+Each version flake exposes:
+
+- `packages.<system>.default` / `packages.<system>.matrix-synapse` -- the wrapped package
+- `packages.<system>.matrix-synapse-unwrapped` -- the unwrapped package
+- `overlays.default` -- overlay providing both `matrix-synapse` and `matrix-synapse-unwrapped`
+
+To upgrade a site, change the `dir=` parameter to the new version and run `nix flake lock --update-input matrix-synapse-pinned`.
+
+## Maintenance
+
+This provider is actively maintained by [Guardian Project](https://guardianproject.info).
+
+### Issues
+
+For bug reports and feature requests, please use the [Issues][issues] page.
+
+### Security
+
+For security-related issues, please contact us through our [security policy][sec].
+
+[issues]: https://guardianproject.dev/ops/nix-matrix-pkgs/issues
+[sec]: https://guardianproject.info/contact/
+
+## License
+
+Copyright (c) 2026 Abel Luck <abel@guardianproject.info>
+
+This project is licensed under the GNU General Public License v3.0 or later - see the [LICENSE](LICENSE) file for details.