diff --git a/README.md b/README.md
index 20299dd..2b4a59d 100644
--- a/README.md
+++ b/README.md
@@ -153,6 +153,11 @@ version (`--major-label`, `--minor-label` and `--patch-label` rename them). It r
and a later run removes only those, never a label a person added. It needs `GITHUB_TOKEN` with `pull-requests: write`.
Without write access, as on a pull request from a fork, it writes the job summary, warns and succeeds.
+With `--fail-on major`, a breaking change fails the check, and the comment says how to go ahead: add the
+`breaking-allowed` label (`--allow-label` renames it). Adding the label runs the workflow again, provided it runs on
+the `labeled` and `unlabeled` events, and the check passes with the change labelled `breaking`. So a breaking change is
+caught, labelled for release-drafter, and merged only once someone says it is intended.
+
### Provider specs
Before it had a command per source, the tool took two provider specs, and `diff` still does, unchanged, for the builds
diff --git a/src/assembly-differ/PullRequests/Comment.cs b/src/assembly-differ/PullRequests/Comment.cs
index fc43392..33fcd29 100644
--- a/src/assembly-differ/PullRequests/Comment.cs
+++ b/src/assembly-differ/PullRequests/Comment.cs
@@ -17,11 +17,24 @@ public static class Comment
/// GitHub refuses a comment over 65536 characters; the details stop well before that.
private const int MaxLength = 60000;
- public static string Render(JsonElement report, IReadOnlyCollection labels)
+ public static string Render(JsonElement report, IReadOnlyCollection labels, Gate gate = Gate.None, string allowLabel = "")
{
var body = new StringBuilder();
body.AppendLine(Marker);
body.AppendLine(LabelsMarkerPrefix + string.Join(",", labels) + " -->");
+ switch (gate)
+ {
+ case Gate.Blocked:
+ body.AppendLine(
+ allowLabel.Length > 0
+ ? $"> [!CAUTION]\n> This check fails on this change. If it is intended, add the `{allowLabel}` label to allow it.\n"
+ : "> [!CAUTION]\n> This check fails on this change.\n"
+ );
+ break;
+ case Gate.Allowed:
+ body.AppendLine($"> [!NOTE]\n> The `{allowLabel}` label allows this change.\n");
+ break;
+ }
if (report.TryGetProperty("firstRelease", out var first) && first.GetBoolean())
{
diff --git a/src/assembly-differ/PullRequests/PullRequestCommand.cs b/src/assembly-differ/PullRequests/PullRequestCommand.cs
index a02f7ca..0089de0 100644
--- a/src/assembly-differ/PullRequests/PullRequestCommand.cs
+++ b/src/assembly-differ/PullRequests/PullRequestCommand.cs
@@ -5,10 +5,19 @@
using System.Net;
using System.Text.Json;
using System.Threading.Tasks;
+using Differ;
using Nullean.Argh;
namespace Differ.PullRequests;
+/// Whether a change at --fail-on holds the check back.
+public enum Gate
+{
+ None,
+ Allowed,
+ Blocked,
+}
+
internal sealed class PullRequestCommand
{
///
@@ -20,22 +29,28 @@ internal sealed class PullRequestCommand
/// hidden marker and updated, and the labels this tool set are recorded in it: a later run swaps only those, never a
/// label a person added. It needs GITHUB_TOKEN with pull-requests: write. Without write access, as on a pull request
/// from a fork, it writes the job summary, warns and succeeds; outside a pull request it writes the job summary only.
+ /// With --fail-on, a change at that level fails the check until someone adds the allow label, breaking-allowed by
+ /// default; the workflow has to run on the labeled and unlabeled events too, so adding the label runs it again.
///
/// The api-changes.json a command wrote with --format json.
/// The repository as owner/name; defaults to GITHUB_REPOSITORY.
/// The pull request number; defaults to the one in GITHUB_EVENT_PATH.
+ /// Exit with code 4 when the suggested version change is at least this, unless the pull request has the allow label; none never fails.
+ /// The label that allows a change at --fail-on, so the check passes; empty allows none.
/// The label for a Major change, matching release-drafter's; empty sets none.
/// The label for a Minor change; empty sets none.
/// The label for a Patch change; empty sets none.
/// Leave the comment alone.
/// Leave the labels alone.
/// assembly-differ release build/output/MyLib.1.3.0.nupkg -f json -o build/output
- /// assembly-differ pull-request build/output/api-changes.json
+ /// assembly-differ pull-request build/output/api-changes.json --fail-on major
[CommandName("pull-request")]
public async Task PullRequest(
[Argument] string report,
string? repository = null,
int? pullRequest = null,
+ SuggestedVersionChange failOn = SuggestedVersionChange.None,
+ string allowLabel = "breaking-allowed",
string majorLabel = "breaking",
string minorLabel = "feature",
string patchLabel = "",
@@ -53,43 +68,64 @@ public async Task PullRequest(
using var document = JsonDocument.Parse(await File.ReadAllTextAsync(report));
var root = document.RootElement;
- var suggested = root.GetProperty("suggestedVersionChange").GetString();
+ var suggestedText = root.GetProperty("suggestedVersionChange").GetString();
+ var suggested = Enum.Parse(suggestedText!, ignoreCase: true);
var label = suggested switch
{
- "Major" => majorLabel,
- "Minor" => minorLabel,
- "Patch" => patchLabel,
+ SuggestedVersionChange.Major => majorLabel,
+ SuggestedVersionChange.Minor => minorLabel,
+ SuggestedVersionChange.Patch => patchLabel,
_ => "",
};
string[] wanted = labels && label.Length > 0 ? [label] : [];
- var body = Comment.Render(root, wanted);
+ var gated = failOn > SuggestedVersionChange.None && suggested >= failOn;
+
+ repository ??= Env("GITHUB_REPOSITORY");
+ pullRequest ??= PullRequestFromEvent();
+ var token = Env("GITHUB_TOKEN") ?? Env("GH_TOKEN");
+ var onPullRequest = repository is not null && pullRequest is not null && !string.IsNullOrEmpty(token);
+ var api = new Uri(Env("GITHUB_API_URL") ?? "https://api.github.com");
+ using var github = onPullRequest ? new GitHubApi(api, token!, repository!, pullRequest!.Value) : null;
+
+ // the labels decide whether a change at --fail-on is allowed, so they are read first
+ IReadOnlyCollection present = [];
+ if (github is not null)
+ {
+ try
+ {
+ present = await github.Labels();
+ }
+ catch (Exception e) when (e is GitHubApiException or System.Net.Http.HttpRequestException)
+ {
+ Console.Error.WriteLine($"[diff] could not read pull request #{pullRequest} in {repository}: {e.Message}");
+ return 1;
+ }
+ }
+ var allowed = gated && allowLabel.Length > 0 && present.Contains(allowLabel, StringComparer.OrdinalIgnoreCase);
+ var gate = !gated ? Gate.None : allowed ? Gate.Allowed : Gate.Blocked;
+ var body = Comment.Render(root, wanted, gate, allowLabel);
var summary = Env("GITHUB_STEP_SUMMARY");
if (!string.IsNullOrEmpty(summary))
await File.AppendAllTextAsync(summary, body + Environment.NewLine);
- repository ??= Env("GITHUB_REPOSITORY");
- pullRequest ??= PullRequestFromEvent();
+ var exitCode = Verdict(gate, suggested, failOn, allowLabel, onPullRequest);
if (repository is null || pullRequest is null)
{
Console.WriteLine("[diff] Not a pull request: wrote the job summary only");
- return 0;
+ return exitCode;
}
-
- var token = Env("GITHUB_TOKEN") ?? Env("GH_TOKEN");
- if (string.IsNullOrEmpty(token))
+ if (github is null)
{
Console.Error.WriteLine("[diff] warning: GITHUB_TOKEN is not set, so the pull request is left as it is");
- return 0;
+ return exitCode;
}
- var api = new Uri(Env("GITHUB_API_URL") ?? "https://api.github.com");
- using var github = new GitHubApi(api, token, repository, pullRequest.Value);
try
{
var existing = await github.FindComment(Comment.Marker);
if (labels)
- await SetLabels(github, existing is { } e ? Comment.LabelsIn(e.Body) : [], wanted);
+ await SetLabels(github, present, existing is { } e ? Comment.LabelsIn(e.Body) : [], wanted);
if (comment)
{
if (existing is { } found)
@@ -98,7 +134,7 @@ public async Task PullRequest(
await github.CreateComment(body);
}
Console.WriteLine($"[diff] Updated pull request #{pullRequest} in {repository}: {suggested}{(wanted.Length > 0 ? $", labelled {wanted[0]}" : "")}");
- return 0;
+ return exitCode;
}
catch (GitHubApiException e) when (e.Status is HttpStatusCode.Forbidden or HttpStatusCode.NotFound or HttpStatusCode.Unauthorized)
{
@@ -106,7 +142,7 @@ public async Task PullRequest(
Console.Error.WriteLine(
$"[diff] warning: the token cannot write to pull request #{pullRequest} ({(int)e.Status}), as on a pull request from a fork; wrote the job summary only"
);
- return 0;
+ return exitCode;
}
catch (Exception e) when (e is GitHubApiException or System.Net.Http.HttpRequestException)
{
@@ -115,10 +151,31 @@ public async Task PullRequest(
}
}
+ /// The exit code: 4 when a change at --fail-on is not allowed, with a line saying why and what to do.
+ private static int Verdict(Gate gate, SuggestedVersionChange suggested, SuggestedVersionChange failOn, string allowLabel, bool onPullRequest)
+ {
+ switch (gate)
+ {
+ case Gate.Allowed:
+ Console.WriteLine($"[diff] The {suggested} change is allowed by the {allowLabel} label");
+ return 0;
+ case Gate.Blocked:
+ var how = onPullRequest && allowLabel.Length > 0 ? $"; add the {allowLabel} label to the pull request to allow it" : "";
+ Console.Error.WriteLine($"[diff] The {suggested} change is at least --fail-on {failOn.ToString().ToLowerInvariant()}{how}");
+ return 4;
+ default:
+ return 0;
+ }
+ }
+
/// Removes the labels this tool set before and no longer wants, and adds the ones it wants.
- private static async Task SetLabels(GitHubApi github, IReadOnlyCollection setBefore, IReadOnlyCollection wanted)
+ private static async Task SetLabels(
+ GitHubApi github,
+ IReadOnlyCollection present,
+ IReadOnlyCollection setBefore,
+ IReadOnlyCollection wanted
+ )
{
- var present = await github.Labels();
foreach (var stale in setBefore.Except(wanted, StringComparer.OrdinalIgnoreCase))
if (present.Contains(stale, StringComparer.OrdinalIgnoreCase))
await github.RemoveLabel(stale);
diff --git a/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.pull-request.cc54f021.verified.txt b/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.pull-request.cc54f021.verified.txt
index 39876aa..c764014 100644
--- a/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.pull-request.cc54f021.verified.txt
+++ b/tests/assembly-differ.Tests/.snapshots/CommandsTests/Help.pull-request.cc54f021.verified.txt
@@ -11,6 +11,9 @@ Global options:
Options:
--repository The repository as owner/name; defaults to GITHUB_REPOSITORY. [default: null]
--pull-request The pull request number; defaults to the one in GITHUB_EVENT_PATH. [default: default]
+ --fail-on Exit with code 4 when the suggested version change is at least this, unless the pull request has the allow label; none never fails. [default: none]
+ One of:
+ --allow-label The label that allows a change at --fail-on, so the check passes; empty allows none. [default: breaking-allowed]
--major-label The label for a Major change, matching release-drafter's; empty sets none. [default: breaking]
--minor-label The label for a Minor change; empty sets none. [default: feature]
--patch-label The label for a Patch change; empty sets none. [default: ]
@@ -23,8 +26,10 @@ Notes:
hidden marker and updated, and the labels this tool set are recorded in it: a later run swaps only those, never a
label a person added. It needs GITHUB_TOKEN with pull-requests: write. Without write access, as on a pull request
from a fork, it writes the job summary, warns and succeeds; outside a pull request it writes the job summary only.
+ With --fail-on, a change at that level fails the check until someone adds the allow label, breaking-allowed by
+ default; the workflow has to run on the labeled and unlabeled events too, so adding the label runs it again.
Examples:
assembly-differ release build/output/MyLib.1.3.0.nupkg -f json -o build/output
- assembly-differ pull-request build/output/api-changes.json
+ assembly-differ pull-request build/output/api-changes.json --fail-on major
diff --git a/tests/assembly-differ.Tests/PullRequestTests.cs b/tests/assembly-differ.Tests/PullRequestTests.cs
index 3c361d6..62e3e32 100644
--- a/tests/assembly-differ.Tests/PullRequestTests.cs
+++ b/tests/assembly-differ.Tests/PullRequestTests.cs
@@ -93,6 +93,66 @@ public async Task Takes_off_its_label_when_nothing_changes_any_more()
github.Comments.Should().ContainSingle().Which.Body.Should().Contain("suggested version change **None**");
}
+ [Test]
+ public async Task Fails_a_breaking_change_until_the_allow_label_is_added()
+ {
+ using var fixture = Scenarios.Create("method-removed");
+ using var github = new FakeGitHub();
+ var report = await ReportFor(fixture, "report");
+
+ var (blocked, _) = await PullRequest(github, fixture, report, true, "--fail-on", "major");
+
+ blocked.ExitCode.Should().Be(4);
+ blocked.Error.Should().Contain("add the breaking-allowed label to the pull request to allow it");
+ github.Labels.Should().Equal("breaking");
+ github.Comments.Should().ContainSingle().Which.Body.Should().Contain("add the `breaking-allowed` label to allow it");
+
+ // the author agrees: adding the label runs the workflow again
+ github.Labels.Add("breaking-allowed");
+ var (allowed, _) = await PullRequest(github, fixture, report, true, "--fail-on", "major");
+
+ allowed.ExitCode.Should().Be(0, allowed.Error);
+ allowed.Out.Should().Contain("The Major change is allowed by the breaking-allowed label");
+ github.Labels.Should().Equal("breaking", "breaking-allowed");
+ github.Comments.Should().ContainSingle().Which.Body.Should().Contain("The `breaking-allowed` label allows this change.");
+ }
+
+ [Test]
+ public async Task A_change_below_fail_on_passes()
+ {
+ using var fixture = Scenarios.Create("method-added");
+ using var github = new FakeGitHub();
+
+ var (result, _) = await PullRequest(github, fixture, await ReportFor(fixture, "report"), true, "--fail-on", "major");
+
+ result.ExitCode.Should().Be(0, result.Error);
+ github.Labels.Should().Equal("feature");
+ }
+
+ [Test]
+ public async Task The_allow_label_can_be_renamed()
+ {
+ using var fixture = Scenarios.Create("method-removed");
+ using var github = new FakeGitHub();
+ github.Labels.Add("api-break-ok");
+
+ var (result, _) = await PullRequest(github, fixture, await ReportFor(fixture, "report"), true, "--fail-on", "major", "--allow-label", "api-break-ok");
+
+ result.ExitCode.Should().Be(0, result.Error);
+ }
+
+ [Test]
+ public async Task Outside_a_pull_request_fail_on_still_applies()
+ {
+ using var fixture = Scenarios.Create("method-removed");
+ using var github = new FakeGitHub();
+
+ var (result, _) = await PullRequest(github, fixture, await ReportFor(fixture, "report"), false, "--fail-on", "major");
+
+ result.ExitCode.Should().Be(4);
+ result.Error.Should().Contain("The Major change is at least --fail-on major").And.NotContain("add the");
+ }
+
[Test]
public async Task Never_removes_a_label_a_person_added()
{
@@ -135,7 +195,7 @@ public async Task Fails_with_a_message_when_GitHub_cannot_be_reached()
var result = await Cli.RunInAsync(fixture.Root, environment, "pull-request", report, "--repository", "owner/repo", "--pull-request", "7");
result.ExitCode.Should().Be(1);
- result.Error.Should().StartWith("[diff] could not update pull request #7 in owner/repo:").And.NotContain(" at ");
+ result.Error.Should().StartWith("[diff] could not read pull request #7 in owner/repo:").And.NotContain(" at ");
}
[Test]