[#142] Stable release asset names, automated release publishing, README install block (#143)

* [#142] Stable release asset names, automated release, README install block

Installing the tool took more inference than it should, and assembling a release
was manual enough to be easy to get wrong.

The release zips now have stable names (UnityDataTool-<os>-<arch>.zip), so
releases/latest/download/ links are permanent and anything automated can fetch a
build without querying the releases API. Pushing a vX.Y.Z tag now builds all
three platforms, writes checksums.txt and creates a draft release with them
attached, leaving only the title and notes to write by hand.

The zips are built in the platform jobs rather than taken from upload-artifact,
which drops the executable permission bit on macOS and Linux.

The README gains an Install section at the top with per-platform commands that
can be copied verbatim, replacing the Downloads section; the agent guide gets the
same commands. Documentation/releasing.md describes cutting a release.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* [#142] Name the install locations and be honest about upgrades

Install into ~/.local/share/UnityDataTool rather than ~/UnityDataTool on macOS
and Linux: a visible app folder at the top of the home directory is not a
convention, while the XDG data directory is the usual home for a per-user tool on
both. Windows keeps %LOCALAPPDATA%\Programs\UnityDataTool, which is where
per-user app installs go. The prose now names both paths instead of saying "a
directory", and points at the dest variable for installing elsewhere.

Re-running the commands overwrites what the new release ships but leaves behind
any file the release dropped, so say so and mention deleting the directory first
for an exact copy.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: SkowronskiAndrew

.github/workflows/.build.yml

@@ -74,8 +74,60 @@ jobs:
           cp -R Documentation "$dest/"
         shell: bash
 
+      # The zip is built here rather than relying on the one upload-artifact produces, because
+      # that one drops the executable permission bit on macOS and Linux.
+      - name: Package (Windows)
+        if: matrix.os == 'windows'
+        run: |
+          New-Item -ItemType Directory -Force dist | Out-Null
+          Compress-Archive -Path "publish/${{ matrix.os }}/${{ matrix.arch }}-${{ env.environment }}/*" -DestinationPath "dist/UnityDataTool-${{ matrix.os }}-${{ matrix.arch }}.zip"
+        shell: pwsh
+
+      - name: Package (macOS / Linux)
+        if: matrix.os != 'windows'
+        run: |
+          mkdir -p dist
+          package="$GITHUB_WORKSPACE/dist/UnityDataTool-${{ matrix.os }}-${{ matrix.arch }}.zip"
+          (cd "publish/${{ matrix.os }}/${{ matrix.arch }}-${{ env.environment }}" && zip -qr "$package" .)
+        shell: bash
+
       - name: Upload artifact
         uses: actions/upload-artifact@v4
         with:
           name: UnityDataTool-${{ matrix.os }}-${{ matrix.arch }}-${{ env.environment }}
-          path: publish/${{ matrix.os }}/${{ matrix.arch }}-${{ env.environment }}
+          path: dist/UnityDataTool-${{ matrix.os }}-${{ matrix.arch }}.zip
+
+  # Pushing a vX.Y.Z tag assembles the release, so the zips always come from a reproducible
+  # build of the tagged commit and no platform can be left out by hand. The release is left as
+  # a draft: the remaining step is to write its title and notes, then publish it.
+  release:
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download the platform packages
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+          pattern: UnityDataTool-*-release
+          merge-multiple: true
+
+      - name: Generate checksums
+        run: |
+          (cd dist && sha256sum *.zip | tee checksums.txt)
+        shell: bash
+
+      - name: Create or update the draft release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          if gh release view "$TAG" --repo "$GITHUB_REPOSITORY" > /dev/null 2>&1; then
+            gh release upload "$TAG" dist/* --repo "$GITHUB_REPOSITORY" --clobber
+          else
+            gh release create "$TAG" dist/* --repo "$GITHUB_REPOSITORY" --draft --generate-notes --title "$TAG"
+          fi
+        shell: bash

AGENTS.md

@@ -25,6 +25,9 @@ dotnet build UnityDataTool/UnityDataTool.csproj -c Release
 
 Output location (Windows): `UnityDataTool\bin\Release\net9.0\UnityDataTool.exe`
 
+Releases are built and published by the "Build UnityDataTool" action when a `vX.Y.Z` tag is pushed;
+the process is described in `Documentation/releasing.md`.
+
 ### Publishing (Mac-specific)
 ```bash
 # Intel Mac

Documentation/agent-guide.md

@@ -7,6 +7,31 @@ individual files and objects. This page is the recommended workflow, plus the ha
 are not obvious from `--help` and tend to cost the most discovery time. It is written so it can be
 pasted (or linked) into an agent's context, and it is just as useful for humans writing scripts.
 
+## Getting the tool
+
+If `UnityDataTool` is not already on the `PATH`, the latest release can be downloaded and unzipped
+in one step. The asset name selects the platform: `UnityDataTool-windows-x64.zip`,
+`UnityDataTool-macos-arm64.zip`, or `UnityDataTool-linux-x64.zip`.
+
+```bash
+dest=~/.local/share/UnityDataTool
+curl -fsSL -o /tmp/UnityDataTool.zip https://github.com/Unity-Technologies/UnityDataTools/releases/latest/download/UnityDataTool-linux-x64.zip
+unzip -oq /tmp/UnityDataTool.zip -d "$dest" && "$dest/UnityDataTool" --version
+```
+
+```powershell
+$dest = "$env:LOCALAPPDATA\Programs\UnityDataTool"
+Invoke-WebRequest https://github.com/Unity-Technologies/UnityDataTools/releases/latest/download/UnityDataTool-windows-x64.zip -OutFile "$env:TEMP\UnityDataTool.zip"
+Expand-Archive "$env:TEMP\UnityDataTool.zip" -DestinationPath $dest -Force
+& "$dest\UnityDataTool.exe" --version
+```
+
+The zip is self-contained (the executable, the native library it loads, and an offline copy of this
+documentation), so a successful `--version` means the tool is ready to use. Re-running the same
+commands upgrades an existing install, overwriting what the new release ships without removing files
+it has dropped. See the [Install section of the README](../README.md#install) for PATH and macOS
+notes.
+
 ## The core loop
 
 1. **Analyze the build output into a database.** One build per database (see below).

Documentation/releasing.md

@@ -0,0 +1,61 @@
+# Releasing UnityDataTool
+
+A release is a git tag plus a GitHub release with one zip per platform. The build and the upload are
+automated: pushing a `vX.Y.Z` tag runs the "Build UnityDataTool" action, which publishes a **draft**
+release with the zips and their checksums attached. What is left is the version bookkeeping around
+the tag and writing the release notes.
+
+## The version convention
+
+`UnityDataTool/UnityDataTool.csproj` holds the version. On `main` the `InformationalVersion` always
+carries a `-dev` suffix (for example `2.3.0-dev`), which is what `--version` reports and what makes
+the documentation link in `--help` point at `main`. A release strips that suffix, so a tagged binary
+reports a bare `2.3.0` and links to the docs as they were at the tag.
+
+Immediately after tagging, `main` moves to the *next* `-dev` version. That way work can land on
+`main` right after a release without landing on a version number that has already shipped.
+
+## Steps
+
+1. Check that the tests are green on `main`:
+   <https://github.com/Unity-Technologies/UnityDataTools/actions>.
+
+2. Drop the `-dev` suffix from `InformationalVersion`, commit as `Release vX.Y.Z`, then tag and push
+   both:
+
+   ```
+   git tag vX.Y.Z
+   git push origin main
+   git push origin vX.Y.Z
+   ```
+
+3. Bump `main` to the next version: `AssemblyVersion` and `FileVersion` to `X.Y+1.0.0`,
+   `InformationalVersion` to `X.Y+1.0-dev`. Commit and push.
+
+4. The tag push builds `UnityDataTool-windows-x64.zip`, `UnityDataTool-macos-arm64.zip` and
+   `UnityDataTool-linux-x64.zip`, writes `checksums.txt`, and creates the draft release. Confirm all
+   four assets arrived:
+
+   ```
+   gh release view vX.Y.Z
+   ```
+
+5. Write the notes and publish. The generated notes list the merged PRs; a short summary of the
+   user-visible changes on top of them is what most readers actually read.
+
+   ```
+   gh release edit vX.Y.Z --title "vX.Y.Z <short description>" --draft=false
+   ```
+
+Steps 2 and 3 are mechanical and worth scripting if you cut releases often.
+
+## Why the asset names have no version in them
+
+`https://github.com/Unity-Technologies/UnityDataTools/releases/latest/download/UnityDataTool-windows-x64.zip`
+only works as a permanent download link while the asset names stay the same from release to release.
+The README and the agent guide hand those URLs to users, so the names should not be changed or have
+the version added back into them. The version is in the release title, in `checksums.txt`, and in
+`--version`.
+
+Re-running the action for a tag that already has a release re-uploads the assets over the existing
+ones, so a failed or incomplete run can simply be re-run.

README.md

@@ -12,6 +12,60 @@ The tool also provides comprehensive analysis of **Unity Addressables build repo
 
 The command line tool uses the UnityFileSystemApi library to access the content of Unity Archives and Serialized files, which are Unity's primary binary formats. This repository also serves as a reference for how this library could be used as part of incorporating functionality into your own tools.
 
+## Install
+
+Builds for Windows, macOS (Apple Silicon) and Linux are attached to every
+[release](https://github.com/Unity-Technologies/UnityDataTools/releases). They are self-contained:
+a zip holds the `UnityDataTool` executable, the native `UnityFileSystemApi` library it uses, and an
+offline copy of this README and the `Documentation/` folder. Nothing else needs to be installed, not
+even a .NET runtime.
+
+The commands below download the latest release, unzip it, and print the version. They install into
+`%LOCALAPPDATA%\Programs\UnityDataTool` on Windows and `~/.local/share/UnityDataTool` on macOS and
+Linux; set `dest` to something else to install anywhere you like, such as a shared tools directory.
+
+**Windows** (PowerShell)
+
+```powershell
+$dest = "$env:LOCALAPPDATA\Programs\UnityDataTool"
+Invoke-WebRequest https://github.com/Unity-Technologies/UnityDataTools/releases/latest/download/UnityDataTool-windows-x64.zip -OutFile "$env:TEMP\UnityDataTool.zip"
+Expand-Archive "$env:TEMP\UnityDataTool.zip" -DestinationPath $dest -Force
+& "$dest\UnityDataTool.exe" --version
+```
+
+**macOS** (Apple Silicon)
+
+```bash
+dest=~/.local/share/UnityDataTool
+curl -fsSL -o /tmp/UnityDataTool.zip https://github.com/Unity-Technologies/UnityDataTools/releases/latest/download/UnityDataTool-macos-arm64.zip
+unzip -oq /tmp/UnityDataTool.zip -d "$dest" && "$dest/UnityDataTool" --version
+```
+
+**Linux** (x64)
+
+```bash
+dest=~/.local/share/UnityDataTool
+curl -fsSL -o /tmp/UnityDataTool.zip https://github.com/Unity-Technologies/UnityDataTools/releases/latest/download/UnityDataTool-linux-x64.zip
+unzip -oq /tmp/UnityDataTool.zip -d "$dest" && "$dest/UnityDataTool" --version
+```
+
+Add the install directory to your `PATH` to run the tool as `UnityDataTool` from anywhere. The
+`releases/latest/download/` links always resolve to the newest release, and `checksums.txt` on the
+release page holds the SHA-256 of each zip.
+
+A few things worth knowing:
+
+* To upgrade, run the same commands again. They overwrite everything the new release ships, but they
+  do not remove a file that it has dropped, so a renamed documentation page can survive as a stale
+  copy. Delete the install directory first for an install that matches the release exactly.
+* On macOS, downloading with `curl` avoids the quarantine flag that a browser download sets. After a
+  browser download, macOS may refuse to load `UnityFileSystemApi.dylib` until it is allowed under
+  System Settings > Privacy & Security.
+* Intel Macs have no published build; [build from source](#how-to-build) instead.
+* Each release describes what changed. For changes that are not in a release yet, see the
+  [commit history](https://github.com/Unity-Technologies/UnityDataTools/commits/main/) and
+  [build from source](#how-to-build).
+
 ## Documentation
 
 New to Unity's data files or to UnityDataTool? These topics are a good place to start.
@@ -121,16 +175,6 @@ shared test data doubles as convenient sample content for ad hoc use of the tool
 * UnityProjects: two Unity projects (`Baseline` and `LeadingEdge`) used to regenerate some of the test
   data as Unity evolves.
 
-## Downloads
-
-Prebuilt Windows, Mac, and Linux builds are published on the [Releases page](https://github.com/Unity-Technologies/UnityDataTools/releases). Each release includes a zip per platform containing the `UnityDataTool` executable, the native libraries it needs, and this README plus the matching `Documentation/` folder so the docs are available offline.
-
-To use:
-1. Download and unzip the build for your platform.
-2. Run UnityDataTool from the extracted location, or add that location to your system PATH.
-
-Each release describes what changed; refer to the [commit history](https://github.com/Unity-Technologies/UnityDataTools/commits/main/) for changes since the latest release. To try unreleased changes, [build from source](#how-to-build).
-
 ## Getting UnityFileSystemApi
 
 UnityDataTool uses the pre-compiled `UnityFileSystemApi` library to read Unity Archives and SerializedFiles. **Normally you don't need to do anything with this library.** The repository already includes a recent Windows, Mac, and Linux copy in the [`UnityFileSystem/`](https://github.com/Unity-Technologies/UnityDataTools/tree/main/UnityFileSystem) directory, and using that bundled copy is the recommended way to run the tool.
@@ -154,6 +198,9 @@ On Windows, the executable is written to `UnityDataTool\bin\Release\net9.0`. Add
 
 See the [command-line tool documentation](./Documentation/unitydatatool.md) for usage instructions.
 
+Maintainers: see [Releasing UnityDataTool](./Documentation/releasing.md) for how a release is cut
+and published.
+
 ## Origins
 
 This tool is the evolution of the [AssetBundle Analyzer](https://github.com/faelenor/asset-bundle-analyzer)