Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
15 changes: 14 additions & 1 deletion src/assembly-differ/PullRequests/Comment.cs
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,24 @@ public static class Comment
/// <summary>GitHub refuses a comment over 65536 characters; the details stop well before that.</summary>
private const int MaxLength = 60000;

public static string Render(JsonElement report, IReadOnlyCollection<string> labels)
public static string Render(JsonElement report, IReadOnlyCollection<string> 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())
{
Expand Down
97 changes: 77 additions & 20 deletions src/assembly-differ/PullRequests/PullRequestCommand.cs
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,19 @@
using System.Net;
using System.Text.Json;
using System.Threading.Tasks;
using Differ;
using Nullean.Argh;

namespace Differ.PullRequests;

/// <summary>Whether a change at --fail-on holds the check back.</summary>
public enum Gate
{
None,
Allowed,
Blocked,
}

internal sealed class PullRequestCommand
{
/// <summary>
Expand All @@ -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.
/// </remarks>
/// <param name="report">The api-changes.json a command wrote with --format json.</param>
/// <param name="repository">The repository as owner/name; defaults to GITHUB_REPOSITORY.</param>
/// <param name="pullRequest">The pull request number; defaults to the one in GITHUB_EVENT_PATH.</param>
/// <param name="failOn">Exit with code 4 when the suggested version change is at least this, unless the pull request has the allow label; none never fails.</param>
/// <param name="allowLabel">The label that allows a change at --fail-on, so the check passes; empty allows none.</param>
/// <param name="majorLabel">The label for a Major change, matching release-drafter's; empty sets none.</param>
/// <param name="minorLabel">The label for a Minor change; empty sets none.</param>
/// <param name="patchLabel">The label for a Patch change; empty sets none.</param>
/// <param name="noComment">Leave the comment alone.</param>
/// <param name="noLabels">Leave the labels alone.</param>
/// <example>assembly-differ release build/output/MyLib.1.3.0.nupkg -f json -o build/output</example>
/// <example>assembly-differ pull-request build/output/api-changes.json</example>
/// <example>assembly-differ pull-request build/output/api-changes.json --fail-on major</example>
[CommandName("pull-request")]
public async Task<int> 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 = "",
Expand All @@ -53,43 +68,64 @@ public async Task<int> 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<SuggestedVersionChange>(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<string> 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)
Expand All @@ -98,15 +134,15 @@ public async Task<int> 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)
{
// a pull request from a fork gets a read-only token
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)
{
Expand All @@ -115,10 +151,31 @@ public async Task<int> PullRequest(
}
}

/// <summary>The exit code: 4 when a change at --fail-on is not allowed, with a line saying why and what to do.</summary>
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;
}
}

/// <summary>Removes the labels this tool set before and no longer wants, and adds the ones it wants.</summary>
private static async Task SetLabels(GitHubApi github, IReadOnlyCollection<string> setBefore, IReadOnlyCollection<string> wanted)
private static async Task SetLabels(
GitHubApi github,
IReadOnlyCollection<string> present,
IReadOnlyCollection<string> setBefore,
IReadOnlyCollection<string> 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);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,9 @@ Global options:
Options:
--repository <string> The repository as owner/name; defaults to GITHUB_REPOSITORY. [default: null]
--pull-request <value> The pull request number; defaults to the one in GITHUB_EVENT_PATH. [default: default]
--fail-on <enum> 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: <none|patch|minor|major>
--allow-label <string> The label that allows a change at --fail-on, so the check passes; empty allows none. [default: breaking-allowed]
--major-label <string> The label for a Major change, matching release-drafter's; empty sets none. [default: breaking]
--minor-label <string> The label for a Minor change; empty sets none. [default: feature]
--patch-label <string> The label for a Patch change; empty sets none. [default: ]
Expand All @@ -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
62 changes: 61 additions & 1 deletion tests/assembly-differ.Tests/PullRequestTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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()
{
Expand Down Expand Up @@ -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]
Expand Down
Loading