From 257ccbb217d9f49f0026a7bbb6d864883719cab8 Mon Sep 17 00:00:00 2001
From: tomos <tomos@synonym.to>
Date: Wed, 4 Mar 2026 09:43:35 +0000
Subject: [PATCH 1/7] Revert "chore: pubky-testnet v0.7.2 (#334)"

This reverts commit 34e6530c04eed6caa466819c594c8fdbf32dbf6d.
---
 Cargo.lock                 | 2 +-
 pubky-testnet/CHANGELOG.md | 6 ------
 pubky-testnet/Cargo.toml   | 2 +-
 3 files changed, 2 insertions(+), 8 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 9bc133cf..d24b8f1b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -4099,7 +4099,7 @@ dependencies = [
 
 [[package]]
 name = "pubky-testnet"
-version = "0.7.2"
+version = "0.7.1"
 dependencies = [
  "anyhow",
  "clap",
diff --git a/pubky-testnet/CHANGELOG.md b/pubky-testnet/CHANGELOG.md
index 8befcc66..4c753083 100644
--- a/pubky-testnet/CHANGELOG.md
+++ b/pubky-testnet/CHANGELOG.md
@@ -2,12 +2,6 @@
 
 All notable changes to the `pubky-testnet` crate will be documented in this file.
 
-## [0.7.2] - 2026-03-01
-
-### Changed
-
-- Set explicit versions for all workspace dependencies in `Cargo.toml` for better reproducibility when publishing
-
 ## [0.7.1] - 2026-02-27
 
 ### Changed
diff --git a/pubky-testnet/Cargo.toml b/pubky-testnet/Cargo.toml
index 1074f2e4..352e7797 100644
--- a/pubky-testnet/Cargo.toml
+++ b/pubky-testnet/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 name = "pubky-testnet"
 description = "A local test network for Pubky Core development."
-version = "0.7.2"
+version = "0.7.1"
 edition.workspace = true
 authors.workspace = true
 license.workspace = true

From eb78b13b4c1e008184349e32f23d50f7e107f718 Mon Sep 17 00:00:00 2001
From: tomos <tomos@synonym.to>
Date: Wed, 4 Mar 2026 09:43:58 +0000
Subject: [PATCH 2/7] Revert "chore: pubky-testnet `0.7` docs and workflow
 improvements (#333)"

This reverts commit 3ed01d323f711db6456a345235f78d0e157b4571.
---
 .github/workflows/pr-check.yml |  7 +------
 CONTRIBUTORS.md                |  6 ++----
 pubky-testnet/CHANGELOG.md     | 38 ----------------------------------
 pubky-testnet/Cargo.toml       |  2 +-
 pubky-testnet/README.md        |  2 +-
 5 files changed, 5 insertions(+), 50 deletions(-)
 delete mode 100644 pubky-testnet/CHANGELOG.md

diff --git a/.github/workflows/pr-check.yml b/.github/workflows/pr-check.yml
index 9b51bd8b..de4d3a62 100644
--- a/.github/workflows/pr-check.yml
+++ b/.github/workflows/pr-check.yml
@@ -275,13 +275,8 @@ jobs:
           profile: minimal
           toolchain: 1.89
           override: true
-      - name: Cache Rust
+      - name: Cache
         uses: Swatinem/rust-cache@v2
-      - name: Cache Embedded-postgres binaries
-        uses: actions/cache@v4
-        with:
-          path: /home/runner/.cache/pubky-testnet/postgresql
-          key: postgres-embedded-${{ runner.os }}
       - name: Run embedded postgres tests
         run: |
           cargo test -p pubky-testnet \
diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
index 3f9bb3fc..ef281dbb 100644
--- a/CONTRIBUTORS.md
+++ b/CONTRIBUTORS.md
@@ -19,15 +19,13 @@
     - Assign a reviewer. Every PR needs to be reviewed at least once. More reviews are possible on request.
 5. Always squash the PR when merging. One commit == one feature/fix.
 
-
 ## Releasing a crate
 
 1. Bump the crate version: `./.scripts/set-version.sh $VERSION crate-name`
    - Example: `./.scripts/set-version.sh 0.7.0 pubky-testnet`
 2. **If the crate depends on other workspace crates that changed, update those dependency versions in `Cargo.toml`.**
-3. Update the `CHANGELOG.md` with the new version
-4. Create and merge a PR with the version bump titled: `chore: crate-name vx.x.x`.
-5. Publish the crate: `./.scripts/publish-libs.sh crate-name`
+3. Create and merge a PR with the version bump titled: `chore: crate-name vx.x.x`.
+4. Publish the crate: `./.scripts/publish-libs.sh crate-name`
    - Example: `./.scripts/publish-libs.sh pubky-testnet`
 
 **Note:** Dependencies must be published before dependents. For example, if `pubky-homeserver` needs a new version of `pubky-common`, publish `pubky-common` first, then update the version in `pubky-homeserver/Cargo.toml`, then publish `pubky-homeserver`.
diff --git a/pubky-testnet/CHANGELOG.md b/pubky-testnet/CHANGELOG.md
deleted file mode 100644
index 4c753083..00000000
--- a/pubky-testnet/CHANGELOG.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# Changelog
-
-All notable changes to the `pubky-testnet` crate will be documented in this file.
-
-## [0.7.1] - 2026-02-27
-
-### Changed
-
-- Set explicit versions for internal pubky dependencies in `Cargo.toml`
-
-## [0.7.0] - 2026-02-26
-
-### Added
-
-- Embedded Postgres support via `embedded-postgres` feature flag, allowing tests to run without an external Postgres instance
-- Unique data directories per embedded Postgres instance to prevent conflicts in parallel test runs
-
-### Changed
-
-- Bumped `pkarr`, `mainline`, and `pkarr-relay` dependencies
-
-### Fixed
-
-- README instructions for running local cargo tests
-- macOS test compatibility
-
-## [0.6.0] - 2026-01-13
-
-### Features
-
-- **Builder pattern** for `EphemeralTestnet` configuration, enabling custom keypairs, configs, and HTTP relay settings
-- **Random keypair generation** option for ephemeral testnets
-- **Configurable relay host** for Docker environments
-- **Static testnet configuration** support
-- Postgres database backend support (replacing LMDB)
-- Flexible files backend (Google Bucket, local filesystem, in-memory)
-- Optional admin server
-- Docker support with configurable ports
diff --git a/pubky-testnet/Cargo.toml b/pubky-testnet/Cargo.toml
index 352e7797..7fafc3ae 100644
--- a/pubky-testnet/Cargo.toml
+++ b/pubky-testnet/Cargo.toml
@@ -15,7 +15,7 @@ categories = ["web-programming", "authentication", "cryptography"]
 [dependencies]
 anyhow = "1.0.101"
 pkarr-relay = "0.11.4"
-tokio = { version = "1.49.0", features = ["rt-multi-thread", "macros", "signal"] }
+tokio = { version = "1.49.0", features = ["full"] }
 tracing-subscriber = "0.3.22"
 url = "2.5.8"
 
diff --git a/pubky-testnet/README.md b/pubky-testnet/README.md
index d8e0fbb3..a085dc3f 100644
--- a/pubky-testnet/README.md
+++ b/pubky-testnet/README.md
@@ -12,7 +12,7 @@ For testing without a separate Postgres installation, enable the `embedded-postg
 
 ```toml
 [dev-dependencies]
-pubky-testnet = { version = "0.7", features = ["embedded-postgres"] }
+pubky-testnet = { version = "0.6", features = ["embedded-postgres"] }
 ```
 
 ```rust,no_run

From 21d23c0503163ef0e5fe9a7fdaa424b679ead3fa Mon Sep 17 00:00:00 2001
From: tomos <tomos@synonym.to>
Date: Wed, 4 Mar 2026 09:44:18 +0000
Subject: [PATCH 3/7] Revert "feat: set-version.sh and publish-libs.sh to be
 per-crate only (#325)"

This reverts commit 9525efc0384feb0e2bbe82b77f10ddd33a0b338b.
---
 .scripts/publish-libs.sh | 37 ++++++++-------------
 .scripts/set-version.sh  | 69 ++++++++++++++++------------------------
 CONTRIBUTORS.md          | 36 +++++++++------------
 3 files changed, 56 insertions(+), 86 deletions(-)

diff --git a/.scripts/publish-libs.sh b/.scripts/publish-libs.sh
index 8b216a30..a586bf55 100755
--- a/.scripts/publish-libs.sh
+++ b/.scripts/publish-libs.sh
@@ -1,38 +1,29 @@
 #!/bin/bash
 
 # -------------------------------------------------------------------------------------------------
-# This script publishes a crate to crates.io.
-#
-# Usage:
-#   ./publish-libs.sh pubky-testnet   # Publish pubky-testnet
-#   ./publish-libs.sh pubky           # Publish pubky + npm package
+# This script publishes all the crates of the workspace to crates.io.
 # -------------------------------------------------------------------------------------------------
 
 set -e # fail the script if any command fails
 set -u # fail the script if any variable is not set
 set -o pipefail # fail the script if any pipe command fails
 
-# Check arguments
-if [ $# -ne 1 ]; then
-  echo "Error: Crate name required."
-  echo "Usage: $0 <crate>"
-  echo ""
-  echo "Examples:"
-  echo "  $0 pubky-testnet   # Publish pubky-testnet"
-  echo "  $0 pubky           # Publish pubky + npm package"
+# Check if cargo-set-version is installed
+if ! cargo --list | grep -q "workspaces"; then
+  echo "Error: cargo-workspaces is not installed but required."
+  echo "Please install it first by running:"
+  echo "  cargo install cargo-workspaces"
   exit 1
 fi
 
-CRATE=$1
 
-# Publish the crate
-echo "Publishing $CRATE..."
-cargo publish -p "$CRATE"
+# Publish all the crates of the workspace to crates.io.
+# ws does this in the correct order on how crates are depended on each other.
+echo "Publishing all the crates of the workspace to crates.io..."
+cargo ws publish --no-git-commit --publish-as-is
 
-# Publish npm package if pubky
-if [ "$CRATE" = "pubky" ]; then
-  echo "Publishing the npm package to npmjs.com..."
-  (cd pubky-sdk/bindings/js/pkg && npm ci && npm run build && npm publish)
-fi
+# Publish the npm package to npmjs.com.
+echo "Publishing the npm package to npmjs.com..."
+(cd pubky-sdk/bindings/js/pkg && npm ci && npm run build && npm publish)
 
-echo "Done"
+echo "Done"
\ No newline at end of file
diff --git a/.scripts/set-version.sh b/.scripts/set-version.sh
index f72176f1..c41373d2 100755
--- a/.scripts/set-version.sh
+++ b/.scripts/set-version.sh
@@ -1,30 +1,30 @@
 #!/bin/bash
 
 # -------------------------------------------------------------------------------------------------
-# This script sets the version of a workspace crate.
-#
-# Usage:
-#   ./set-version.sh 0.7.0 pubky-testnet   # Set pubky-testnet to 0.7.0
-#   ./set-version.sh 0.7.0 pubky           # Set pubky + npm package
+# This script sets the version of all members of the workspace.
+# It also updates the inner member dependency versions.
 # -------------------------------------------------------------------------------------------------
 
 set -e # fail the script if any command fails
 set -u # fail the script if any variable is not set
 set -o pipefail # fail the script if any pipe command fails
 
-# Check if the version and crate are provided
-if [ $# -ne 2 ]; then
-  echo "Error: Version and crate name required."
-  echo "Usage: $0 <version> <crate>"
-  echo ""
-  echo "Examples:"
-  echo "  $0 0.7.0 pubky-testnet   # Set pubky-testnet to 0.7.0"
-  echo "  $0 0.7.0 pubky           # Set pubky + npm package"
+# Check if cargo-set-version is installed
+if ! cargo --list | grep -q "set-version"; then
+  echo "Error: cargo-set-version is not installed but required."
+  echo "Please install it first by running:"
+  echo "  cargo install cargo-set-version"
   exit 1
 fi
 
+
+# Check if the version is provided
 NEW_VERSION=$1
-CRATE=$2
+if [ -z "$NEW_VERSION" ]; then
+  echo "Error: New version not specified."
+  echo "Usage: $0 <new_version>"
+  exit 1
+fi
 
 # Rough semver format validation
 SEMVER_REGEX="^([0-9]+)\.([0-9]+)\.([0-9]+)(-([0-9A-Za-z.-]+))?(\+([0-9A-Za-z.-]+))?$"
@@ -34,38 +34,23 @@ if [[ ! "$NEW_VERSION" =~ $SEMVER_REGEX ]]; then
 fi
 
 # Ask for confirmation to update the version
-read -p "Are you sure you want to set the version to $NEW_VERSION for $CRATE? (y/N) " -n 1 -r
+read -p "Are you sure you want to set the version to $NEW_VERSION? (y/N) " -n 1 -r
 echo
-if [[ ! $REPLY =~ ^[Yy]$ ]]; then
-  echo "Version change cancelled."
-  exit 1
+if [[ ! $REPLY =~ ^[Yy]$ ]]
+then
+    echo "Version change cancelled."
+    exit 1
 fi
 
-# Map crate name to directory (pubky crate lives in pubky-sdk dir)
-CRATE_DIR="$CRATE"
-if [ "$CRATE" = "pubky" ]; then
-  CRATE_DIR="pubky-sdk"
-fi
+# Update the pubky-sdk package.json
+echo "Updating pubky-sdk package.json version to $NEW_VERSION..."
+(cd pubky-sdk/bindings/js/pkg && npm version --no-git-tag-version --allow-same-version "$NEW_VERSION")
 
-# Find the crate's Cargo.toml
-MANIFEST_PATH="$CRATE_DIR/Cargo.toml"
-if [ ! -f "$MANIFEST_PATH" ]; then
-  echo "Error: Could not find $MANIFEST_PATH"
-  exit 1
-fi
+# Set the version of all rust members of the workspace
+# cargo set-version also updates the inner member dependency versions.
+echo "Setting the version of all rust members of the workspace to $NEW_VERSION..."
+cargo set-version $NEW_VERSION
 
-# Set version for the crate (update first version = "x.x.x" line in [package] section)
-echo "Setting $CRATE to $NEW_VERSION..."
-# Use portable sed -i syntax (BSD/macOS requires '' argument, GNU/Linux does not)
-case "$OSTYPE" in
-    darwin*) sed -i '' 's/^version = ".*"$/version = "'"$NEW_VERSION"'"/' "$MANIFEST_PATH" ;;
-    *)       sed -i 's/^version = ".*"$/version = "'"$NEW_VERSION"'"/' "$MANIFEST_PATH" ;;
-esac
 
-# Update npm package if pubky
-if [ "$CRATE" = "pubky" ]; then
-  echo "Updating npm package version to $NEW_VERSION..."
-  (cd pubky-sdk/bindings/js/pkg && npm version --no-git-tag-version --allow-same-version "$NEW_VERSION")
-fi
 
-echo "Done"
+echo Done
diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
index ef281dbb..168a3c71 100644
--- a/CONTRIBUTORS.md
+++ b/CONTRIBUTORS.md
@@ -19,24 +19,18 @@
     - Assign a reviewer. Every PR needs to be reviewed at least once. More reviews are possible on request.
 5. Always squash the PR when merging. One commit == one feature/fix.
 
-## Releasing a crate
-
-1. Bump the crate version: `./.scripts/set-version.sh $VERSION crate-name`
-   - Example: `./.scripts/set-version.sh 0.7.0 pubky-testnet`
-2. **If the crate depends on other workspace crates that changed, update those dependency versions in `Cargo.toml`.**
-3. Create and merge a PR with the version bump titled: `chore: crate-name vx.x.x`.
-4. Publish the crate: `./.scripts/publish-libs.sh crate-name`
-   - Example: `./.scripts/publish-libs.sh pubky-testnet`
-
-**Note:** Dependencies must be published before dependents. For example, if `pubky-homeserver` needs a new version of `pubky-common`, publish `pubky-common` first, then update the version in `pubky-homeserver/Cargo.toml`, then publish `pubky-homeserver`.
-
-### Releasing pubky-homeserver
-
-`pubky-homeserver` is the only crate that needs a GitHub release with binary artifacts (other crates are libraries consumed via crates.io/npm).
-
-After publishing to crates.io, create a [new Github release](https://github.com/pubky/pubky-core/releases/new):
-- Tag: `vx.x.x`
-- Title: `vx.x.x`
-- Description: Changelog for this release.
-- Upload artifacts from the [build-artifacts.yml workflow](./.github/workflows/build-artifacts.yml).
-  You can find them in [Github Actions](https://github.com/pubky/pubky-core/actions?query=branch%3Amain) for the main commit.
+## Versioning
+
+1. Merge all PRs in the main branch that you want to include in the next version.
+2. Update versions of all crates and npm package with `./.scripts/set-version.sh $NEW_SEMVER_VERSION`.
+3. Create a PR with the title: `chore: vx.x.x`.
+4. Let the PR review and squash + merge.
+5. Publish crates and npm package.
+  - Checkout the `main` branch with the new version merged.
+  - Run `./.scripts/publish-libs.sh`.
+6. Create a [new Github release](https://github.com/pubky/pubky-core/releases/new).
+    - Tag: `vx.x.x`
+    - Title: `vx.x.x`
+    - Description: Changelog for the current version.
+    - Upload the different artifacts created by the [build-artifacts.yml workflow](./.github/workflows/build-artifacts.yml). 
+    You can find them in [Github Actions](https://github.com/pubky/pubky-core/actions?query=branch%3Amain) for the new main commit.

From 391d10cd419f760bdb683442e1d1b277678fe3f9 Mon Sep 17 00:00:00 2001
From: tomos <tomos@synonym.to>
Date: Wed, 4 Mar 2026 09:44:38 +0000
Subject: [PATCH 4/7] Revert "chore: pubky_testnet set explicit versions in
 cargo.toml (#328)"

This reverts commit 24bd2b71212c6d73cd2082f3b161d8284f9280a7.
---
 Cargo.lock               |  2 +-
 pubky-testnet/Cargo.toml | 20 ++++++++++----------
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index d24b8f1b..067c8dc7 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -4099,7 +4099,7 @@ dependencies = [
 
 [[package]]
 name = "pubky-testnet"
-version = "0.7.1"
+version = "0.7.0"
 dependencies = [
  "anyhow",
  "clap",
diff --git a/pubky-testnet/Cargo.toml b/pubky-testnet/Cargo.toml
index 7fafc3ae..8e860332 100644
--- a/pubky-testnet/Cargo.toml
+++ b/pubky-testnet/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 name = "pubky-testnet"
 description = "A local test network for Pubky Core development."
-version = "0.7.1"
+version = "0.7.0"
 edition.workspace = true
 authors.workspace = true
 license.workspace = true
@@ -13,11 +13,11 @@ keywords = ["pkarr", "pubky", "testnet", "testing"]
 categories = ["web-programming", "authentication", "cryptography"]
 
 [dependencies]
-anyhow = "1.0.101"
-pkarr-relay = "0.11.4"
-tokio = { version = "1.49.0", features = ["full"] }
-tracing-subscriber = "0.3.22"
-url = "2.5.8"
+anyhow.workspace = true
+pkarr-relay = { workspace = true }
+tokio = { workspace = true, features = ["full"] }
+tracing-subscriber.workspace = true
+url.workspace = true
 
 pubky = { path = "../pubky-sdk", version = "0.6.0", features = ["json"] }
 pubky-common = { path = "../pubky-common", version = "0.6.0" }
@@ -27,10 +27,10 @@ pubky-homeserver = { path = "../pubky-homeserver", version = "0.6.0", default-fe
 pubky_test_utils = { path = "../test_utils/pubky_test", version = "0.1.0" }
 http-relay = { path = "../http-relay", version = "0.5.1" }
 tempfile = "3.19.1"
-tracing = "0.1.44"
-pkarr = { version = "5.0.3", default-features = false, features = ["relays"] }
-mainline = "6.1.1"
-clap = "4.5.58"
+tracing.workspace = true
+pkarr = { workspace = true }
+mainline = { workspace = true }
+clap.workspace = true
 dirs = "6.0.0"
 once_cell = "1.21.3"
 postgresql_embedded = { version = "0.20", optional = true }

From 2ca17d525897781dfdf5a43b9d21d5ac84f307ef Mon Sep 17 00:00:00 2001
From: tomos <tomos@synonym.to>
Date: Wed, 4 Mar 2026 09:45:10 +0000
Subject: [PATCH 5/7] Revert "chore: pubky-testnet v0.7.0 (#326)"

This reverts commit 9a136b537e9653fc95070e4a64c47138ed4945bb.
---
 Cargo.lock               | 2 +-
 examples/rust/Cargo.toml | 2 +-
 pubky-testnet/Cargo.toml | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 067c8dc7..54b3ee9e 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -4099,7 +4099,7 @@ dependencies = [
 
 [[package]]
 name = "pubky-testnet"
-version = "0.7.0"
+version = "0.6.0"
 dependencies = [
  "anyhow",
  "clap",
diff --git a/examples/rust/Cargo.toml b/examples/rust/Cargo.toml
index aa97b8e7..2767fe42 100644
--- a/examples/rust/Cargo.toml
+++ b/examples/rust/Cargo.toml
@@ -46,7 +46,7 @@ anyhow.workspace = true
 base64 = "0.22.1"
 clap = { version = "4.5.48", features = ["derive"] }
 pubky = { path = "../../pubky-sdk", version = "0.6.0" }
-pubky-testnet = { path = "../../pubky-testnet", version = "0.7.2" }
+pubky-testnet = { path = "../../pubky-testnet", version = "0.6.0" }
 pubky-common = { path = "../../pubky-common", version = "0.6.0" }
 reqwest.workspace = true
 rpassword = "7.4.0"
diff --git a/pubky-testnet/Cargo.toml b/pubky-testnet/Cargo.toml
index 8e860332..e495c554 100644
--- a/pubky-testnet/Cargo.toml
+++ b/pubky-testnet/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 name = "pubky-testnet"
 description = "A local test network for Pubky Core development."
-version = "0.7.0"
+version = "0.6.0"
 edition.workspace = true
 authors.workspace = true
 license.workspace = true

From b9b8af07e2d49fcfaf55c27921f3f85cadf60be1 Mon Sep 17 00:00:00 2001
From: tomos <tomos@synonym.to>
Date: Wed, 4 Mar 2026 09:48:30 +0000
Subject: [PATCH 6/7] fix: Cache embedded postgres

---
 .github/workflows/pr-check.yml | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/pr-check.yml b/.github/workflows/pr-check.yml
index de4d3a62..9b51bd8b 100644
--- a/.github/workflows/pr-check.yml
+++ b/.github/workflows/pr-check.yml
@@ -275,8 +275,13 @@ jobs:
           profile: minimal
           toolchain: 1.89
           override: true
-      - name: Cache
+      - name: Cache Rust
         uses: Swatinem/rust-cache@v2
+      - name: Cache Embedded-postgres binaries
+        uses: actions/cache@v4
+        with:
+          path: /home/runner/.cache/pubky-testnet/postgresql
+          key: postgres-embedded-${{ runner.os }}
       - name: Run embedded postgres tests
         run: |
           cargo test -p pubky-testnet \

From cf67105c170f5d871affeb0e56ba07d171c1bc44 Mon Sep 17 00:00:00 2001
From: tomos <tomos@synonym.to>
Date: Wed, 4 Mar 2026 10:59:38 +0000
Subject: [PATCH 7/7] docs: Justification for releasing modules together

---
 CONTRIBUTORS.md | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
index 168a3c71..d02803e6 100644
--- a/CONTRIBUTORS.md
+++ b/CONTRIBUTORS.md
@@ -21,6 +21,34 @@
 
 ## Versioning
 
+### Unified Version Policy
+
+The following crates are released together on the same version schedule:
+
+- `pubky-sdk`
+- `pubky-homeserver`
+- `pubky-testnet`
+- `pubky-common`
+
+**All four crates always share the same version number.** When any of these crates is released, all are released together with the same version.
+
+This policy exists for **clarity and compatibility guarantees**:
+
+1. **Compatibility assurance**: When `pubky-sdk` and `pubky-homeserver` share the same version (e.g., both at `0.6.0`), users know they are compatible and jointly tested. There's no guesswork about which SDK version works with which homeserver.
+
+2. **Testing clarity**: As a developer, your production code uses `pubky::Client` and your tests use `pubky_testnet::Testnet`. When both are at `0.7.0`, you know your tests exercise the exact same client behavior you'll get in production.
+
+### What If Only One Crate Needs Changes?
+
+If a change affects only one crate (e.g., a testnet-only feature), we still release all crates together:
+
+- **Minor changes**: Wait to bundle with other changes, or release all crates with the patch bump.
+- **Urgent changes**: Consider a pre-release version like `0.6.1-rc.1` if you absolutely cannot wait. This signals "this is not a full release" while keeping versions aligned.
+
+**Do not** release crates independently. The short-term convenience is not worth the long-term confusion it causes for users trying to match compatible versions.
+
+### Release Process
+
 1. Merge all PRs in the main branch that you want to include in the next version.
 2. Update versions of all crates and npm package with `./.scripts/set-version.sh $NEW_SEMVER_VERSION`.
 3. Create a PR with the title: `chore: vx.x.x`.
@@ -32,5 +60,5 @@
     - Tag: `vx.x.x`
     - Title: `vx.x.x`
     - Description: Changelog for the current version.
-    - Upload the different artifacts created by the [build-artifacts.yml workflow](./.github/workflows/build-artifacts.yml). 
+    - Upload the different artifacts created by the [build-artifacts.yml workflow](./.github/workflows/build-artifacts.yml).
     You can find them in [Github Actions](https://github.com/pubky/pubky-core/actions?query=branch%3Amain) for the new main commit.