diff --git a/.github/workflows/package.yml b/.github/workflows/package.yml
index d1e9f40b1..5326d5e82 100644
--- a/.github/workflows/package.yml
+++ b/.github/workflows/package.yml
@@ -23,6 +23,11 @@ on:
version:
description: 'Ably version, e.g. 2.0.1 (must equal src/CommonAssemblyInfo.cs on the chosen branch)'
required: true
+ workflow_call:
+ inputs:
+ version:
+ required: true
+ type: string
permissions:
contents: read
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 000000000..d6df808ca
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,155 @@
+# ============================================================================
+# RELEASE: checks and packs Ably.PubSub.Core, .Device and .Server for release.
+# Publishing isn't part of this workflow yet.
+#
+# gh workflow run release.yml --ref main -f version=2.0.1 -f dry_run=true
+# gh workflow run release.yml --ref main -f version=2.0.1 -f dry_run=false
+#
+# Don't break:
+# - The file name. nuget.org Trusted Publishing trusts only release.yml, and only
+# a NuGet/login in this file (the publish job, added later) in environment `nuget`.
+# - The `version` input's name. package.yml, called by `pack`, reads
+# github.event.inputs.version.
+#
+# The checks are in cake-build/release.cake ("Release targets" in cake-build/README.md).
+# ============================================================================
+
+name: Release
+
+on:
+ workflow_dispatch:
+ inputs:
+ # Keep the name `version`: package.yml reads github.event.inputs.version.
+ version:
+ description: 'Version to release, e.g. 2.0.1. Must equal the top CHANGELOG.md entry and the committed version files on main.'
+ required: true
+ type: string
+ dry_run:
+ description: 'Check, pack and test only. Push nothing, create no tag or release.'
+ required: true
+ type: boolean
+ default: true
+
+permissions: {}
+
+# One real release at a time, never cancelled (a cancelled publish can leave Core
+# without the doors). Each dry run gets its own group.
+concurrency:
+ group: ${{ inputs.dry_run && format('release-dry-run-{0}', github.run_id) || 'release-nuget' }}
+ cancel-in-progress: false
+
+env:
+ VERSION: ${{ inputs.version }}
+
+jobs:
+ prechecks:
+ runs-on: ubuntu-24.04
+ timeout-minutes: 10
+ permissions:
+ contents: read
+ env:
+ DOTNET_NOLOGO: true
+ DRY_RUN: ${{ inputs.dry_run }}
+ steps:
+ # A failing step, not a job-level `if:`, so a wrong ref fails the run instead of skipping it.
+ - name: Refuse anything but main
+ run: |
+ if [ "$GITHUB_REF" != "refs/heads/main" ]; then
+ echo "::error::release.yml only runs on main (dispatched on $GITHUB_REF)."
+ exit 1
+ fi
+
+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+ with:
+ persist-credentials: false
+
+ # The repo's .NET 6 baseline; global.json (rollForward: latestMajor) may pick a newer preinstalled SDK.
+ - uses: actions/setup-dotnet@67a3573c9a986a3f9c594539f4ab511d57bb3ce9 # v4.3.1
+ with:
+ dotnet-version: 6.0.428
+
+ - name: Restore the Cake tool
+ run: dotnet tool restore
+
+ # On a dry run, "already on nuget.org, tagged or released" only warns.
+ - name: Check the version, CHANGELOG.md, and that it isn't released yet
+ env:
+ GITHUB_TOKEN: ${{ github.token }}
+ run: dotnet cake cake-build/release.cake -- --target=Release.Preflight "--version=$VERSION" "--dryRun=$DRY_RUN"
+
+ pack:
+ needs: prechecks
+ # A called workflow can only narrow the token it is given: this grants package.yml's contents: read.
+ permissions:
+ contents: read
+ uses: ./.github/workflows/package.yml
+ with:
+ version: ${{ inputs.version }}
+
+ plan:
+ needs: pack
+ runs-on: ubuntu-24.04
+ timeout-minutes: 10
+ permissions:
+ contents: read
+ env:
+ DOTNET_NOLOGO: true
+ DRY_RUN: ${{ inputs.dry_run }}
+ steps:
+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+ with:
+ persist-credentials: false
+
+ - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+ with:
+ name: output-package
+ path: output-package
+
+ # The repo's .NET 6 baseline; global.json (rollForward: latestMajor) may pick a newer preinstalled SDK.
+ - uses: actions/setup-dotnet@67a3573c9a986a3f9c594539f4ab511d57bb3ce9 # v4.3.1
+ with:
+ dotnet-version: 6.0.428
+
+ - name: Restore the Cake tool
+ run: dotnet tool restore
+
+ - name: Extract the release notes
+ run: dotnet cake cake-build/release.cake -- --target=Release.Notes "--version=$VERSION" --output=release-notes/release-notes.md
+
+ # overwrite: re-running this job replaces the notes with the same content.
+ - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+ with:
+ name: release-notes
+ path: release-notes/release-notes.md
+ if-no-files-found: error
+ overwrite: true
+
+ - name: Summarise the release
+ run: |
+ {
+ echo "### Release $VERSION ($([ "$DRY_RUN" = true ] && echo 'DRY RUN' || echo 'REAL'))"
+ echo "Commit: \`$GITHUB_SHA\`"
+ echo
+ echo "Push order: Ably.PubSub.Core, wait for nuget.org, then Ably.PubSub.Device and Ably.PubSub.Server."
+ echo
+ echo '
'
+ (cd output-package && sha256sum -- *)
+ echo '
'
+ echo
+ echo 'Release notes
'
+ echo
+ cat release-notes/release-notes.md
+ echo
+ echo ' '
+ } >> "$GITHUB_STEP_SUMMARY"
+
+ # Until the publish job exists, say so, so a green REAL run isn't taken for a release.
+ - name: Warn that nothing was published
+ if: ${{ !inputs.dry_run }}
+ run: |
+ msg="Publishing isn't part of release.yml yet: this dry_run=false run pushed nothing to nuget.org and created no tag or GitHub release."
+ echo "::warning::$msg"
+ printf '\n**Warning:** %s\n' "$msg" >> "$GITHUB_STEP_SUMMARY"
+
+ - name: Check the Unity package contents
+ run: dotnet cake cake-build/release.cake -- --target=Release.VerifyUnityPackage "--version=$VERSION" "--unityPackage=output-package/ably.pubsub.$VERSION.unitypackage"
diff --git a/cake-build/README.md b/cake-build/README.md
index 2ccc8e7cf..c20a185da 100644
--- a/cake-build/README.md
+++ b/cake-build/README.md
@@ -218,6 +218,39 @@ CLR, and the macOS (Mono) workflow, where they run on Mono.
On macOS/Linux, `Package` needs Mono: it builds the core's `net46` head with Mono
MSBuild and the other target frameworks with the .NET SDK.
+## Release targets
+
+`cake-build/release.cake` holds the checks and the release notes that the release
+workflow (`.github/workflows/release.yml`) runs. It is a separate script, not part
+of `build.cake`: it builds nothing, needs only the .NET SDK and Cake from
+"Prerequisites", and runs on any OS. Run it from the repository root, with the
+arguments after `--`:
+
+```bash
+dotnet tool restore
+dotnet cake cake-build/release.cake -- --target=Release.Preflight --version=2.0.1
+```
+
+- `Release.Preflight` checks that the version is `MAJOR.MINOR.PATCH[-prerelease]`,
+ that the top `CHANGELOG.md` entry is
+ `## [](https://github.com/ably/ably-pubsub-dotnet/tree/) (yyyy-mm-dd)`
+ with a non-empty section, and that the version isn't on nuget.org (for any of
+ the three package IDs) and has no tag or GitHub release yet. `--dryRun=true`
+ reports the "already released" problems as warnings instead of failing. Run it
+ on the release branch before opening the release PR. It calls the nuget.org and
+ GitHub APIs; set `GITHUB_TOKEN` if GitHub rate-limits unauthenticated calls.
+- `Release.VerifyUnityPackage` checks that a `.unitypackage` holds
+ `Assets/Ably/Plugins/Ably.PubSub.Device.dll` and an `Assets/Ably/version.txt`
+ that reads the version. Pass the file with `--unityPackage=`; the default
+ is `ably.pubsub..unitypackage` at the repository root, where
+ `./package-unity.sh` writes it.
+- `Release.Notes` writes the version's `CHANGELOG.md` section, without its heading
+ and "Full Changelog" line, to `--output=` (default `release-notes.md`).
+ The workflow uses it as the GitHub release notes.
+
+`--changelog=` points the targets at another `CHANGELOG.md`. Relative paths
+are resolved against the repository root.
+
## Advanced Options
### Build with specific configuration
diff --git a/cake-build/release.cake b/cake-build/release.cake
new file mode 100644
index 000000000..7f4676f7a
--- /dev/null
+++ b/cake-build/release.cake
@@ -0,0 +1,632 @@
+///////////////////////////////////////////////////////////////////////////////
+// RELEASE CHECKS AND NOTES
+///////////////////////////////////////////////////////////////////////////////
+// The checks and the release notes for .github/workflows/release.yml. Standalone:
+// not loaded by build.cake. Usage and targets: "Release targets" in
+// cake-build/README.md. Arguments go after a -- separator (Cake reserves --version):
+//
+// dotnet cake cake-build/release.cake -- --target=Release.Preflight --version=2.0.1
+
+using System.IO.Compression;
+using System.Net.Http;
+using System.Text;
+using System.Text.Json;
+using System.Text.RegularExpressions;
+
+///////////////////////////////////////////////////////////////////////////////
+// ARGUMENTS
+///////////////////////////////////////////////////////////////////////////////
+
+var target = Argument("target", "Release.Preflight");
+var version = Argument("version", "");
+var dryRun = Argument("dryRun", false);
+
+// The repository root: Cake's working directory is the script's, cake-build/.
+var root = MakeAbsolute(Directory("../"));
+
+var changelogFile = RepoPath(Argument("changelog", "CHANGELOG.md"));
+var unityPackageFile = RepoPath(Argument("unityPackage", $"ably.pubsub.{version}.unitypackage"));
+var notesFile = RepoPath(Argument("output", "release-notes.md"));
+
+// The repository whose tags and releases P7 checks: the one the workflow runs in.
+// A nonexistent repository answers 404, which reads as "absent", so a local run
+// against a fork must pass the right --repository.
+var repository = Argument("repository", EnvironmentVariable("GITHUB_REPOSITORY") ?? "ably/ably-pubsub-dotnet");
+
+// Overridable only to test the failure handling against another host.
+var nugetFlatContainerUrl = Argument("nugetFlatContainerUrl", "https://api.nuget.org/v3-flatcontainer");
+var githubApiUrl = Argument("githubApiUrl", "https://api.github.com");
+
+// The packages released together, Core first (the order they are pushed in).
+var releasePackageIds = new[] { "Ably.PubSub.Core", "Ably.PubSub.Device", "Ably.PubSub.Server" };
+
+// 15 s per attempt keeps the worst case (5 GETs x 4 attempts) inside the prechecks
+// job's 10-minute timeout, so it reports its problems instead of being cancelled.
+var http = new HttpClient { Timeout = TimeSpan.FromSeconds(15) };
+http.DefaultRequestHeaders.UserAgent.ParseAdd("ably-pubsub-dotnet-release-cake");
+
+///////////////////////////////////////////////////////////////////////////////
+// HELPERS
+///////////////////////////////////////////////////////////////////////////////
+
+public FilePath RepoPath(string path)
+{
+ FilePath candidate = path;
+ return candidate.IsRelative ? root.CombineWithFilePath(candidate) : candidate;
+}
+
+public string RequireVersionArgument()
+{
+ if (string.IsNullOrWhiteSpace(version))
+ {
+ throw new Exception(
+ "No --version was supplied. Pass it after a -- separator, e.g. " +
+ "dotnet cake cake-build/release.cake -- --target=Release.Preflight --version=2.0.1 " +
+ "(Cake reserves --version for itself).");
+ }
+
+ return version;
+}
+
+public bool IsOnGitHubActions()
+{
+ return BuildSystem.GitHubActions.IsRunningOnGitHubActions;
+}
+
+// An annotation in Actions (Cake's log colours its lines, which hides a ::warning::
+// prefix from GitHub), a plain warning otherwise.
+public void ReportWarning(string message)
+{
+ if (IsOnGitHubActions())
+ {
+ BuildSystem.GitHubActions.Commands.Warning(message);
+ }
+ else
+ {
+ Warning("{0}", message);
+ }
+}
+
+// Annotates every error in Actions, then fails the task once with all of them.
+public void FailIfAny(List errors, string what)
+{
+ if (errors.Count == 0)
+ {
+ return;
+ }
+
+ if (IsOnGitHubActions())
+ {
+ foreach (var error in errors)
+ {
+ BuildSystem.GitHubActions.Commands.Error(error);
+ }
+ }
+
+ throw new Exception(
+ $"{what} failed with {errors.Count} problem(s):\n\n - " + string.Join("\n\n - ", errors) + "\n");
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// VERSION AND CHANGELOG
+///////////////////////////////////////////////////////////////////////////////
+
+// SemVer 2.0 without build metadata, which nuget.org ignores: no leading v, no +build.
+public bool IsReleaseVersion(string candidate)
+{
+ return Regex.IsMatch(
+ candidate,
+ @"\A(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?\z");
+}
+
+public string[] ReadChangelog()
+{
+ if (!FileExists(changelogFile))
+ {
+ throw new Exception($"{changelogFile.FullPath} not found.");
+ }
+
+ // ReadAllLines also drops a trailing \r, in case the file is checked out with CRLF.
+ return System.IO.File.ReadAllLines(changelogFile.FullPath);
+}
+
+// The lines under the heading at headingIndex, up to the next "## [" heading, without
+// the "[Full Changelog]" line. Leading and trailing blank lines are removed, and blank
+// lines in between are emptied.
+public List ChangelogSection(string[] lines, int headingIndex)
+{
+ var section = lines
+ .Skip(headingIndex + 1)
+ .TakeWhile(line => !line.StartsWith("## ["))
+ .Where(line => !line.StartsWith("[Full Changelog]"))
+ .Select(line => string.IsNullOrWhiteSpace(line) ? "" : line)
+ .SkipWhile(line => line.Length == 0)
+ .ToList();
+
+ while (section.Count > 0 && section[section.Count - 1].Length == 0)
+ {
+ section.RemoveAt(section.Count - 1);
+ }
+
+ return section;
+}
+
+// P3. The top entry must read "## [2.0.0](https://github.com/ably/ably-pubsub-dotnet/tree/2.0.0) (2026-11-03)",
+// so a placeholder date (TBD, Unreleased) fails, and its section becomes the release notes.
+public void CheckChangelogTopEntry(string releaseVersion, List errors)
+{
+ var lines = ReadChangelog();
+ var headingIndex = Array.FindIndex(lines, line => line.StartsWith("## ["));
+ var heading = headingIndex < 0 ? "(none)" : lines[headingIndex];
+ var expected = $"## [{releaseVersion}](https://github.com/ably/ably-pubsub-dotnet/tree/{releaseVersion}) (yyyy-mm-dd)";
+
+ var match = Regex.Match(
+ heading,
+ @"\A## \[([^\]]+)\]\(https://github\.com/ably/ably-pubsub-dotnet/tree/([^)]+)\) \(([0-9]{4}-[0-9]{2}-[0-9]{2})\)\z");
+ if (!match.Success || match.Groups[1].Value != releaseVersion || match.Groups[2].Value != releaseVersion)
+ {
+ errors.Add($"The top CHANGELOG.md entry is '{heading}'. Expected '{expected}'. Add the {releaseVersion} entry in the release PR.");
+ return;
+ }
+
+ var section = ChangelogSection(lines, headingIndex);
+ if (section.Count == 0)
+ {
+ errors.Add($"The CHANGELOG.md {releaseVersion} entry has no content. It becomes the GitHub release notes.");
+ return;
+ }
+
+ Information($"CHANGELOG.md: {heading} (non-blank lines: {section.Count(line => line.Length > 0)}).");
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// REMOTE STATE (fail closed: only a 404 means "absent")
+///////////////////////////////////////////////////////////////////////////////
+
+public class HttpResult
+{
+ // 0 when no response was received.
+ public int Status { get; set; }
+ public string Body { get; set; } = "";
+ public string Failure { get; set; } = "";
+
+ public string Describe(string url)
+ {
+ if (Status == 0)
+ {
+ return $"GET {url} failed: {Failure}";
+ }
+
+ var snippet = Body.Replace("\r", " ").Replace("\n", " ").Trim();
+ if (snippet.Length > 200)
+ {
+ snippet = snippet.Substring(0, 200) + "...";
+ }
+
+ return $"GET {url} returned HTTP {Status}" + (snippet.Length > 0 ? $": {snippet}" : ".");
+ }
+}
+
+// GET with up to 3 retries on a network error, a timeout, 429 or 5xx, as curl --retry does.
+public HttpResult HttpGet(string url, bool gitHubApi)
+{
+ const int attempts = 4;
+ var result = new HttpResult();
+ for (var attempt = 1; attempt <= attempts; attempt++)
+ {
+ try
+ {
+ using (var request = new HttpRequestMessage(HttpMethod.Get, url))
+ {
+ if (gitHubApi)
+ {
+ request.Headers.Accept.ParseAdd("application/vnd.github+json");
+ var token = EnvironmentVariable("GITHUB_TOKEN");
+ if (!string.IsNullOrEmpty(token))
+ {
+ request.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);
+ }
+ }
+
+ using (var response = http.SendAsync(request).GetAwaiter().GetResult())
+ {
+ result = new HttpResult
+ {
+ Status = (int)response.StatusCode,
+ Body = response.Content.ReadAsStringAsync().GetAwaiter().GetResult()
+ };
+ }
+ }
+
+ if (result.Status != 429 && result.Status < 500)
+ {
+ return result;
+ }
+ }
+ catch (Exception e) when (e is HttpRequestException || e is TaskCanceledException)
+ {
+ result = new HttpResult { Failure = e.Message };
+ }
+
+ if (attempt < attempts)
+ {
+ System.Threading.Thread.Sleep(TimeSpan.FromSeconds(2 * attempt));
+ }
+ }
+
+ return result;
+}
+
+// The root of a JSON body, or null if the body isn't a JSON object.
+public JsonElement? ParseJsonObject(string body)
+{
+ try
+ {
+ using (var document = JsonDocument.Parse(body))
+ {
+ return document.RootElement.ValueKind == JsonValueKind.Object
+ ? document.RootElement.Clone()
+ : (JsonElement?)null;
+ }
+ }
+ catch (JsonException)
+ {
+ return null;
+ }
+}
+
+// P6. The flat container lists listed and unlisted versions, in lower case, and
+// returns 404 for an ID with no versions.
+public void CheckNotOnNuGet(string releaseVersion, List released, List errors)
+{
+ foreach (var packageId in releasePackageIds)
+ {
+ var url = $"{nugetFlatContainerUrl}/{packageId.ToLowerInvariant()}/index.json";
+ var response = HttpGet(url, false);
+ if (response.Status == 404)
+ {
+ Information($"{packageId}: no versions on nuget.org yet.");
+ continue;
+ }
+
+ if (response.Status != 200)
+ {
+ errors.Add(response.Describe(url));
+ continue;
+ }
+
+ var index = ParseJsonObject(response.Body);
+ if (index == null
+ || !index.Value.TryGetProperty("versions", out var versions)
+ || versions.ValueKind != JsonValueKind.Array
+ || versions.EnumerateArray().Any(v => v.ValueKind != JsonValueKind.String))
+ {
+ errors.Add($"GET {url} returned HTTP 200 with a body that isn't the expected {{\"versions\": [...]}} JSON.");
+ continue;
+ }
+
+ if (versions.EnumerateArray().Any(v => v.GetString() == releaseVersion.ToLowerInvariant()))
+ {
+ released.Add($"{packageId} {releaseVersion} is already on nuget.org (listed or unlisted). NuGet versions can't be reused: bump the version.");
+ }
+ else
+ {
+ Information($"{packageId}: {releaseVersion} isn't on nuget.org.");
+ }
+ }
+}
+
+// P7, for one of the tag or the release: 404 means absent, a 200 whose `property` is
+// `expected` means present, and anything else is an error.
+public void CheckNotOnGitHub(string path, string property, string expected, string presentMessage, List released, List errors)
+{
+ var url = $"{githubApiUrl}/repos/{repository}/{path}";
+ var response = HttpGet(url, true);
+ if (response.Status == 404)
+ {
+ Information($"{url}: not found.");
+ return;
+ }
+
+ if (response.Status != 200)
+ {
+ errors.Add(response.Describe(url));
+ return;
+ }
+
+ var body = ParseJsonObject(response.Body);
+ if (body != null
+ && body.Value.TryGetProperty(property, out var value)
+ && value.ValueKind == JsonValueKind.String
+ && value.GetString() == expected)
+ {
+ released.Add(presentMessage);
+ return;
+ }
+
+ errors.Add($"GET {url} returned HTTP 200 without the expected \"{property}\": \"{expected}\".");
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// UNITY PACKAGE
+///////////////////////////////////////////////////////////////////////////////
+
+// A .unitypackage is a gzipped tar of / folders, each holding a "pathname" file
+// (the path in the Unity project) and an "asset" file (its content). Returns the
+// content of every asset by its Unity path. Read in memory with a minimal ustar reader
+// (the packager writes plain ustar), because System.Formats.Tar needs .NET 7.
+public Dictionary ReadUnityPackageAssets(FilePath unityPackage)
+{
+ const long maxEntrySize = 256L * 1024 * 1024;
+ var pathnames = new Dictionary();
+ var contents = new Dictionary();
+ var header = new byte[512];
+
+ using (var file = System.IO.File.OpenRead(unityPackage.FullPath))
+ using (var gzip = new GZipStream(file, CompressionMode.Decompress))
+ {
+ while (true)
+ {
+ if (ReadFully(gzip, header, header.Length) < header.Length)
+ {
+ throw new Exception("it ends without the tar end-of-archive marker (truncated?)");
+ }
+
+ if (header.All(b => b == 0))
+ {
+ break;
+ }
+
+ var name = ReadTarHeader(header, out var size, out var type);
+ if (type == 'L' || type == 'K' || type == 'x' || type == 'g')
+ {
+ throw new Exception($"it uses a tar extension (type '{type}') that the Unity packager doesn't write");
+ }
+
+ if (size > maxEntrySize)
+ {
+ throw new Exception($"{name} is larger than {maxEntrySize} bytes");
+ }
+
+ // Only regular files named /pathname or /asset are read; the rest is skipped.
+ var parts = name.TrimStart('.', '/').Split('/');
+ var wanted = (type == '0' || type == '\0') && parts.Length == 2
+ && (parts[1] == "pathname" || parts[1] == "asset");
+ var data = new byte[wanted ? size : 0];
+ if (wanted && ReadFully(gzip, data, data.Length) < data.Length)
+ {
+ throw new Exception($"{name} is truncated");
+ }
+
+ var rest = (size + 511) / 512 * 512 - data.Length;
+ if (SkipFully(gzip, rest) < rest)
+ {
+ throw new Exception($"{name} is truncated");
+ }
+
+ if (wanted && (parts[1] == "pathname" ? pathnames.ContainsKey(parts[0]) : contents.ContainsKey(parts[0])))
+ {
+ throw new Exception($"it holds {name} more than once");
+ }
+
+ if (wanted && parts[1] == "pathname")
+ {
+ // The path is the first line; some Unity versions add a second one.
+ pathnames[parts[0]] = Encoding.UTF8.GetString(data).Split('\n')[0].TrimEnd('\r');
+ }
+ else if (wanted)
+ {
+ contents[parts[0]] = data;
+ }
+ }
+ }
+
+ var assets = new Dictionary();
+ foreach (var pathname in pathnames.Where(p => contents.ContainsKey(p.Key)))
+ {
+ if (assets.ContainsKey(pathname.Value))
+ {
+ throw new Exception($"it holds {pathname.Value} more than once");
+ }
+
+ assets[pathname.Value] = contents[pathname.Key];
+ }
+
+ return assets;
+}
+
+// The entry name of a ustar header, with its size and type flag. Fails on a bad checksum.
+public string ReadTarHeader(byte[] header, out long size, out char type)
+{
+ // The checksum is the sum of all header bytes, with its own 8 bytes counted as spaces.
+ long sum = 0;
+ for (var i = 0; i < header.Length; i++)
+ {
+ sum += i >= 148 && i < 156 ? ' ' : header[i];
+ }
+
+ if (sum != ReadTarOctal(header, 148, 8))
+ {
+ throw new Exception("a tar header has a bad checksum");
+ }
+
+ size = ReadTarOctal(header, 124, 12);
+ type = (char)header[156];
+ var name = ReadTarString(header, 0, 100);
+ // Only POSIX ustar ("ustar\0") has a name prefix; GNU tar keeps timestamps there.
+ var prefix = Encoding.ASCII.GetString(header, 257, 6) == "ustar\0" ? ReadTarString(header, 345, 155) : "";
+ return prefix.Length > 0 ? $"{prefix}/{name}" : name;
+}
+
+public string ReadTarString(byte[] header, int offset, int length)
+{
+ var end = Array.IndexOf(header, (byte)0, offset, length);
+ return Encoding.UTF8.GetString(header, offset, (end < 0 ? offset + length : end) - offset);
+}
+
+public long ReadTarOctal(byte[] header, int offset, int length)
+{
+ var text = Encoding.Latin1.GetString(header, offset, length).Trim(' ', '\0');
+ if (text.Length == 0 || text.Any(c => c < '0' || c > '7'))
+ {
+ throw new Exception($"a tar header has a malformed number field ('{Printable(text)}')");
+ }
+
+ return Convert.ToInt64(text, 8);
+}
+
+// Text from a malformed header, with control and non-ASCII characters escaped.
+public string Printable(string text)
+{
+ return string.Concat(text.Select(c => c >= ' ' && c < 127 ? c.ToString() : $"\\x{(int)c:x2}"));
+}
+
+// Reads until count bytes or the end of the stream; returns the number read.
+public int ReadFully(System.IO.Stream stream, byte[] buffer, int count)
+{
+ var total = 0;
+ int read;
+ while (total < count && (read = stream.Read(buffer, total, count - total)) > 0)
+ {
+ total += read;
+ }
+
+ return total;
+}
+
+public long SkipFully(System.IO.Stream stream, long count)
+{
+ var buffer = new byte[81920];
+ long total = 0;
+ while (total < count)
+ {
+ var read = ReadFully(stream, buffer, (int)Math.Min(buffer.Length, count - total));
+ if (read == 0)
+ {
+ break;
+ }
+
+ total += read;
+ }
+
+ return total;
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// TASKS
+///////////////////////////////////////////////////////////////////////////////
+
+Setup(ctx =>
+{
+ var dryRunNote = target == "Release.Preflight" ? $", dry run: {dryRun}" : "";
+ Information($"Release target: {target}, version: {RequireVersionArgument()}{dryRunNote}");
+});
+
+Task("Release.Preflight")
+ .Description("Check the version, the top CHANGELOG.md entry, and that the version isn't on nuget.org, tagged or released")
+ .Does(() =>
+{
+ var releaseVersion = RequireVersionArgument();
+ var errors = new List();
+ // Problems that only mean "already released": warnings on a dry run, errors otherwise.
+ var released = new List();
+
+ // P2.
+ var isReleaseVersion = IsReleaseVersion(releaseVersion);
+ if (!isReleaseVersion)
+ {
+ errors.Add($"'{releaseVersion}' is not MAJOR.MINOR.PATCH[-prerelease] (no leading v, no +build).");
+ }
+
+ // P3.
+ CheckChangelogTopEntry(releaseVersion, errors);
+
+ // P6 and P7. Skipped for a version that isn't SemVer: it can't be released anyway.
+ if (isReleaseVersion)
+ {
+ CheckNotOnNuGet(releaseVersion, released, errors);
+ CheckNotOnGitHub($"git/ref/tags/{releaseVersion}", "ref", $"refs/tags/{releaseVersion}", $"Tag {releaseVersion} already exists.", released, errors);
+ CheckNotOnGitHub($"releases/tags/{releaseVersion}", "tag_name", releaseVersion, $"GitHub release {releaseVersion} already exists.", released, errors);
+ }
+
+ if (dryRun)
+ {
+ released.ForEach(ReportWarning);
+ }
+ else
+ {
+ errors.AddRange(released);
+ }
+
+ FailIfAny(errors, $"Release pre-flight for {releaseVersion}");
+ Information($"Pre-flight passed for {releaseVersion} (dry run: {dryRun}, warnings: {(dryRun ? released.Count : 0)}).");
+});
+
+// K8. The Unity package has no registry and no install test, and package.yml only
+// checks that the file exists.
+Task("Release.VerifyUnityPackage")
+ .Description("Check the .unitypackage holds the Unity plugin and version.txt at --version")
+ .Does(() =>
+{
+ var releaseVersion = RequireVersionArgument();
+ var name = unityPackageFile.GetFilename().FullPath;
+ if (!FileExists(unityPackageFile))
+ {
+ throw new Exception($"{unityPackageFile.FullPath} not found.");
+ }
+
+ Dictionary assets;
+ try
+ {
+ assets = ReadUnityPackageAssets(unityPackageFile);
+ }
+ catch (Exception e)
+ {
+ throw new Exception($"{name} isn't a readable .unitypackage (a gzipped tar of /pathname and asset files): {e.Message}");
+ }
+
+ var errors = new List();
+ const string pluginPath = "Assets/Ably/Plugins/Ably.PubSub.Device.dll";
+ const string versionPath = "Assets/Ably/version.txt";
+
+ if (!assets.TryGetValue(pluginPath, out var plugin) || plugin.Length == 0)
+ {
+ errors.Add($"{name} has no {pluginPath}, or it is empty.");
+ }
+
+ if (!assets.TryGetValue(versionPath, out var versionFile))
+ {
+ errors.Add($"{name} has no {versionPath}.");
+ }
+ else
+ {
+ var packedVersion = System.Text.Encoding.UTF8.GetString(versionFile).Trim();
+ if (packedVersion != releaseVersion)
+ {
+ errors.Add($"{name} carries {versionPath} '{packedVersion}', expected '{releaseVersion}'.");
+ }
+ }
+
+ FailIfAny(errors, $"Unity package check for {releaseVersion}");
+ Information($"{name} holds {pluginPath} and {versionPath} {releaseVersion}.");
+});
+
+Task("Release.Notes")
+ .Description("Write the CHANGELOG.md section for --version to --output, for the GitHub release")
+ .Does(() =>
+{
+ var releaseVersion = RequireVersionArgument();
+ var lines = ReadChangelog();
+ var headingIndex = Array.FindIndex(lines, line => line.StartsWith($"## [{releaseVersion}]"));
+ var notes = headingIndex < 0 ? new List() : ChangelogSection(lines, headingIndex);
+ if (notes.Count == 0)
+ {
+ throw new Exception($"CHANGELOG.md has no {releaseVersion} section, or it is empty.");
+ }
+
+ EnsureDirectoryExists(notesFile.GetDirectory());
+ System.IO.File.WriteAllText(notesFile.FullPath, string.Join("\n", notes) + "\n");
+ Information($"Wrote the {releaseVersion} release notes ({notes.Count} lines) to {notesFile.FullPath}.");
+});
+
+RunTarget(target);