From 657431822ea92d3616dead49b7d2e10e225c0ec5 Mon Sep 17 00:00:00 2001 From: sacOO7 Date: Wed, 4 Nov 2026 23:39:16 +0530 Subject: [PATCH] Add release workflow with pre-checks and dry run Add .github/workflows/release.yml, dispatched by hand on main with a version and dry_run (default true). It refuses any other ref, runs the pre-checks, packs by calling package.yml, lists the packages with their SHA-256 values in the run summary, checks the contents of the Unity package and extracts the release notes from CHANGELOG.md. The checks and the notes are C# in a new standalone Cake script, cake-build/release.cake, run with `dotnet cake`. It isn't loaded by build.cake, and no existing Cake script changes. Release.Preflight checks the version format and the top CHANGELOG entry, and that the version isn't on nuget.org, tagged or released yet. Only a 404 counts as absent; any other answer fails. Release.VerifyUnityPackage and Release.Notes cover the Unity package and the release notes. The cake-build README documents the targets. The workflow can't publish yet: there is no publish job, no id-token permission and no environment. A run with dry_run=false says so in its summary. Give package.yml a workflow_call trigger with a version input, so the release workflow reuses the same pack, version check and package-install test. Manual dispatch is unchanged. --- .github/workflows/package.yml | 5 + .github/workflows/release.yml | 155 +++++++++ cake-build/README.md | 33 ++ cake-build/release.cake | 632 ++++++++++++++++++++++++++++++++++ 4 files changed, 825 insertions(+) create mode 100644 .github/workflows/release.yml create mode 100644 cake-build/release.cake 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);