ci: add releases.toml automation for compatibility tracking

.github/workflows/ci.yml

@@ -267,3 +267,49 @@ jobs:
         if: github.ref_type == 'tag'
         with:
           files: ${{ env.ZIP_FILE_NAME }}
+
+  update-releases:
+    name: Update releases.toml
+    needs: publish-crates
+    if: github.event_name == 'release' && github.event.action == 'published'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout release tag
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref }}
+
+      - name: Extract crate info from tag
+        id: extract
+        run: |
+          TAG="${{ github.ref_name }}"
+          CRATE_NAME=$(echo "$TAG" | sed -E 's/-[0-9]+\.[0-9]+\.[0-9]+.*//')
+          VERSION=$(echo "$TAG" | sed -E 's/^.*-([0-9]+\.[0-9]+\.[0-9]+.*)/\1/')
+          echo "crate_name=$CRATE_NAME" >> $GITHUB_OUTPUT
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Fetch latest releases.toml from main
+        run: |
+          git fetch origin main
+          git checkout origin/main -- releases.toml 2>/dev/null || true
+
+      - name: Update releases.toml
+        run: ./.github/workflows/scripts/update_releases.sh ${{ steps.extract.outputs.crate_name }} ${{ steps.extract.outputs.version }}
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          base: main
+          branch: chore/releases-${{ github.ref_name }}
+          commit-message: "chore: update releases.toml for ${{ github.ref_name }}"
+          title: "chore: update releases.toml for ${{ github.ref_name }}"
+          body: |
+            Auto-generated PR to update `releases.toml` after publishing `${{ github.ref_name }}`.
+
+            This tracks the dependency versions used in this release for compatibility reference.
+          labels: automated,releases

.github/workflows/scripts/update_releases.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+set -e
+
+# Updates releases.toml with dependency information for a released crate.
+# Usage: update_releases.sh <crate-name> <version>
+#
+# This script extracts resolved dependency versions from Cargo.lock and appends
+# a new entry to releases.toml for compatibility tracking.
+
+err() {
+    echo -e "\e[31m\e[1merror:\e[0m $@" 1>&2;
+}
+
+status() {
+    WIDTH=12
+    printf "\e[32m\e[1m%${WIDTH}s\e[0m %s\n" "$1" "$2"
+}
+
+CRATE_NAME=$1
+VERSION=$2
+RELEASES_FILE="releases.toml"
+
+if [ -z "$CRATE_NAME" ] || [ -z "$VERSION" ]; then
+    err "Usage: update_releases.sh <crate-name> <version>"
+    exit 1
+fi
+
+status "Updating" "$RELEASES_FILE for $CRATE_NAME $VERSION"
+
+DATE=$(date -u +"%Y-%m-%d")
+CRATE_TOML="${CRATE_NAME}/Cargo.toml"
+
+# Extract resolved version from Cargo.lock
+get_lock_version() {
+    local dep_name=$1
+    grep -A1 "name = \"$dep_name\"" Cargo.lock 2>/dev/null | \
+        grep "version = " | head -1 | \
+        sed 's/.*version = "\(.*\)".*/\1/'
+}
+
+# Check if crate depends on a package
+# Matches both `dep = "version"` and `dep.workspace = true` styles
+crate_depends_on() {
+    local dep_pattern=$1
+    grep -qE "^${dep_pattern}([[:space:]]*=|\.)" "$CRATE_TOML" 2>/dev/null
+}
+
+# Only record versions for dependencies the crate actually uses
+SWAY_VERSION=""
+FUEL_CORE_VERSION=""
+FUELS_VERSION=""
+
+if crate_depends_on "sway-core"; then
+    SWAY_VERSION=$(get_lock_version "sway-core")
+fi
+
+if crate_depends_on "fuel-core"; then
+    FUEL_CORE_VERSION=$(get_lock_version "fuel-core")
+fi
+
+if crate_depends_on "fuels"; then
+    FUELS_VERSION=$(get_lock_version "fuels")
+fi
+
+# Create releases.toml if it doesn't exist
+if [ ! -f "$RELEASES_FILE" ]; then
+    cat > "$RELEASES_FILE" << 'EOF'
+# Auto-generated at release time. Do not edit manually.
+# This file tracks which dependency versions each release was built against.
+
+EOF
+    status "Created" "$RELEASES_FILE"
+fi
+
+# Build the TOML entry
+{
+    echo "[[releases]]"
+    echo "crate = \"$CRATE_NAME\""
+    echo "version = \"$VERSION\""
+    echo "date = \"$DATE\""
+
+    [ -n "$SWAY_VERSION" ] && echo "sway = \"$SWAY_VERSION\""
+    [ -n "$FUEL_CORE_VERSION" ] && echo "fuel-core = \"$FUEL_CORE_VERSION\""
+    [ -n "$FUELS_VERSION" ] && echo "fuels-rs = \"$FUELS_VERSION\""
+    echo ""
+} >> "$RELEASES_FILE"
+
+status "Appended" "release entry for $CRATE_NAME $VERSION"

RELEASING.md

@@ -56,6 +56,15 @@ When you publish a GitHub release with a tag like `forc-wallet-0.16.0`, the CI w
   - Example: `forc-wallet-0.16.0-x86_64-unknown-linux-gnu.tar.gz`
 - Uploads all binary archives to the GitHub release
 
+#### 3. Update Compatibility Tracking (`update-releases` job)
+
+- Runs after successful crate publication
+- Extracts dependency versions from `Cargo.lock` (sway, fuel-core, fuels-rs)
+- Appends an entry to `releases.toml` tracking what versions this release was built against
+- Opens a PR to merge the updated `releases.toml` into main
+
+This creates an append-only log of releases and their dependencies, useful for `fuelup` and `fuel.nix` to determine compatible toolchain combinations.
+
 **Key Point:** The CI is fully generic. When you add a new workspace member (e.g., `forc-plugin`) and create a tag `forc-plugin-1.0.0`, the same CI workflow will automatically build and publish that crate without any workflow modifications.
 
 ### Release Checklist

forc-wallet/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 0.16.2 (December 6th, 2025)
+
+No functional changes. Version bump to test `releases.toml` automation.
+
 # 0.16.1 (November 21st, 2025)
 
 ### Changed

forc-wallet/Cargo.toml

@@ -4,7 +4,7 @@ name = "forc-wallet"
 # - Remove path dependencies
 # - Update CHANGELOG.md.
 # - Create "forc-wallet-0.16.x" git tag.
-version = "0.16.1"
+version = "0.16.2"
 description = "A forc plugin for generating or importing wallets using mnemonic phrases."
 edition = "2024"
 authors.workspace = true