From 4a1e2a6f7e6c46ce89a8e43ca7719e4e376e8dc2 Mon Sep 17 00:00:00 2001
From: nxships <2096086+nxships@users.noreply.github.com>
Date: Mon, 25 May 2026 05:19:35 +0200
Subject: [PATCH] docs(releasing): document constraint-floor bump +
 packages.lock refresh
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Hard-won lesson from v0.1.2-test.1: NuGet's PackageReference resolves
to the LOWEST version satisfying the range, not the latest. With a
constraint like [0.1.0,), a freshly-published NexusKit.Modules 0.1.1
keeps building against 0.1.0 unless the floor is moved forward.

Updates step 1 of "Cutting a release" to spell out:
- bump the floor in PlayerNexusTracker.Plugin.csproj (e.g. [0.1.0,) → [0.1.1,))
- refresh packages.lock.json (the sibling-clone swap means it looks
  empty locally for NexusKit refs, which is fine — CI re-evaluates)

Same discipline applies to pre-release / testing builds — without the
floor bump the testing zip ships with the same NuGets as the previous
stable, defeating the point.
---
 RELEASING.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/RELEASING.md b/RELEASING.md
index 2910372..ba53b67 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -4,10 +4,11 @@ PlayerNexusTracker is a Dalamud plugin and uses tag-driven releases. Unlike the
 
 ## Cutting a release
 
-1. **Make sure upstream deps are at the version you expect**. If the Plugin needs new NexusKit or NexusKit.Modules features:
+1. **Make sure upstream deps are at the version you expect, and bump the constraint floor**. If the Plugin needs new NexusKit or NexusKit.Modules features:
    - NexusKit released first (NexusKit's [RELEASING.md](https://github.com/NexusFFXIV/NexusKit/blob/main/RELEASING.md))
    - NexusKit.Modules released next (NexusKit.Modules' [RELEASING.md](https://github.com/NexusFFXIV/NexusKit.Modules/blob/main/RELEASING.md))
-   - Then bump this repo's `PackageReference` constraints if not already covered by floating versions
+   - **Bump the constraint floor in `PlayerNexusTracker.Plugin.csproj`** for every `PackageReference` that should pick up a new version, e.g. `[0.1.0,)` → `[0.1.1,)`. NuGet's `PackageReference` resolves to the **lowest** version satisfying the range, so without raising the floor the build will keep resolving the old release even after a new one is on the feed. Verifiable in CI under "List outdated NuGet dependencies" — if Resolved < Latest for any NexusKit package, the floor still needs bumping.
+   - **Refresh `packages.lock.json`** for the bumped PackageReferences. Locally the sibling-clone swap in `Directory.Build.targets` rewrites NexusKit refs to ProjectReferences and the lock file drops their NuGet entries — that is fine, CI doesn't have the sibling clones and re-evaluates from the csproj on every restore. You can verify by deleting the lock file and running `dotnet restore --force-evaluate` on a clean checkout (or simply rely on CI to surface a mismatch).
 
 2. **Verify `main` is green**:
    ```powershell
@@ -67,6 +68,8 @@ Make sure the same fix lands on `main` so v0.3.0 doesn't regress.
 
 ## Pre-release versions (testing builds)
 
+**Same constraint-floor + lock-file discipline applies as for stable releases.** If the testing build is meant to pick up an upstream lib update (e.g. a fresh NexusKit.Modules patch), step 1 of "Cutting a release" still has to happen first — otherwise the testing zip ships with the same old NuGets as the previous stable tag and the change you wanted to test is missing.
+
 Tag with a suffix containing `-` to publish a testing build instead of a stable release:
 
 ```powershell