From 134c53e01e3923849be740640de6df18d509e727 Mon Sep 17 00:00:00 2001
From: nxships <2096086+nxships@users.noreply.github.com>
Date: Mon, 25 May 2026 05:20:22 +0200
Subject: [PATCH] docs(releasing): correct PackageReference resolution
 behaviour
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Same lesson surfaced via PlayerNexusTracker v0.1.2-test.1. The
pre-release section described [X.Y.Z,) as "floating" and claimed
consumers automatically pick up new stable versions — both wrong.
NuGet's PackageReference resolves to the LOWEST satisfying version,
so promoting consumers to a new stable requires bumping the range
floor in their csprojs + regenerating packages.lock.json. Without
that step, the consumer keeps building against the old version even
with the new one on the feed.
---
 RELEASING.md | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/RELEASING.md b/RELEASING.md
index 4bee0e9..1507c62 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -86,10 +86,16 @@ Suffix conventions (descending stability):
 - `-beta.N` — feature-complete but UI/edge-cases pending
 - `-preview.N` — early feedback, may break
 
-Consumers of NexusKit (NexusKit.Modules, plugins) **stay on their floating `[X.Y.Z,)` `PackageReference`** during pre-release periods — the floating spec ignores pre-releases by default, so stable consumers continue to pull stable versions. A consumer that wants to test against the pre-release pins it explicitly:
+Consumers of NexusKit (NexusKit.Modules, plugins) **keep their existing `[X.Y.Z,)` `PackageReference` ranges** during pre-release periods — `PackageReference` ranges ignore pre-releases by default, so stable consumers continue to resolve the previous stable. A consumer that wants to test against the pre-release pins it explicitly:
 
 ```xml
 <PackageReference Include="NexusKit.Core" Version="0.2.0-rc.1" />
 ```
 
-After validation, cut the stable version (`v0.2.0`) — no separate code change needed, just the tag. Consumers on floating refs automatically pick it up.
+After validation, cut the stable version (`v0.2.0`). **The consumers' constraint floor has to move forward** before they'll actually resolve `0.2.0`: NuGet's `PackageReference` picks the **lowest** version satisfying the range, not the latest, so leaving the floor at `[0.1.0,)` would keep resolving `0.1.0` even with `0.2.0` on the feed. The promotion step is:
+
+1. Bump the range floor in each consumer's csprojs, e.g. `[0.1.0,)` → `[0.2.0,)`
+2. Regenerate `packages.lock.json` (`dotnet restore --force-evaluate`, or rely on CI to refresh on the next push)
+3. Tag the consumer
+
+CI's "List outdated NuGet dependencies" step in each consumer flags this — if `Resolved < Latest` after a NexusKit release, the floor on that consumer still needs raising.