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
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Good-first-issue curation no longer keeps inviting newcomers to issues the contributor relay will not hand out. An advertised issue that a pull request later covers (its `claimed_by_pr` row, `linked-pr`, or `stage/040-covered-by-pr`) now loses `good first issue` and `help wanted` on the next sweep, and its welcome comment is edited to say a pull request covers it; a relay contributor's or person's own claim still keeps the label until the issue closes. The sweep also skips any issue matching `hub.contribute_skip_labels` (`needs-triage` by default, logged as `relay-skip:<label>`), so an untriaged issue is never advertised; an already-advertised issue that later gains such a label keeps its invite, since triage adds and removes it all the time.
25 changes: 20 additions & 5 deletions src/cmd/hive/gfi_wire.go
Original file line number Diff line number Diff line change
Expand Up @@ -101,8 +101,11 @@ func gfiPublicOrigin(cfg *config.Config) string {
// gfiSweepOptions builds the per-call options shared by the sweep and hooks.
func gfiSweepOptions(cfg *config.Config, dashSrv *dashboard.Server, logger *slog.Logger) gfi.SweepOptions {
gc := cfg.GoodFirstIssue
policy := gc.Policy(github.HardSuppressIssueLabels())
// Never advertise what the contributor relay refuses to hand out.
policy.RelaySkip = cfg.Hub.MatchContributeSkipLabel
opts := gfi.SweepOptions{
Policy: gc.Policy(github.HardSuppressIssueLabels()),
Policy: policy,
Links: gfi.Links{Origin: gfiPublicOrigin(cfg), HiveID: cfg.HiveID, DocsBase: gc.DocsURL},
Template: gc.CommentTemplate,
Logger: logger,
Expand Down Expand Up @@ -155,12 +158,14 @@ func gfiCandidates(org string, result *github.ActionableResult, allowed func(str
out = append(out, c)
}
// Issues the enumeration filtered out (blocked, held, parked on a
// person) that still wear the label are handed to the sweep so it can
// withdraw the advertisement (hivecommons/hive#13267); the labels alone
// decide, so the missing body is harmless.
// person) or set aside because a pull request covers them, that still
// wear the label, are handed to the sweep so it can withdraw the
// advertisement (hivecommons/hive#13267); the labels and the coverage
// alone decide, so the missing body is harmless.
for _, repo := range sortedRepoKeys(result.WorkDetailsByRepo) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mixed &&/|| without parentheses. Suggest:

Suggested change
for _, repo := range sortedRepoKeys(result.WorkDetailsByRepo) {
if row.Number <= 0 || (row.Bucket != "filtered" && !covered) || !gfi.HasLabel(row.Labels) {

for _, row := range result.WorkDetailsByRepo[repo].Issues {
if row.Number <= 0 || row.Bucket != "filtered" || !gfi.HasLabel(row.Labels) {
covered := row.Bucket == "claimed_by_pr"
if row.Number <= 0 || row.Bucket != "filtered" && !covered || !gfi.HasLabel(row.Labels) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Readability nit: this condition mixes || and && unparenthesised. Suggest naming the bucket test:

covered := row.Bucket == "claimed_by_pr"
if row.Number <= 0 || !(row.Bucket == "filtered" || covered) || !gfi.HasLabel(row.Labels) {

continue
}
full := qualifyClaimRepo(org, row.Repo)
Expand All @@ -174,6 +179,16 @@ func gfiCandidates(org string, result *github.ActionableResult, allowed func(str
// the label (hivecommons/hive#14613).
c.Body = gfi.TrackingMarker
}
if covered {
c.HasLinkedPR = true
// A relay contributor or person who claimed the issue and
// opened the PR is the outcome the label exists for: it stays
// until the issue closes (gfi.Sweeper.Convert), so Score
// reports "claimed", which is never withdrawn.
if kind := claims.Kind(row.ClaimKind); (kind == claims.KindContributor || kind == claims.KindHuman) && strings.TrimSpace(row.ClaimedBy) != "" {
c.ClaimedBy = row.ClaimedBy
}
}
if labelled[c.Key()] {
continue
}
Expand Down
57 changes: 57 additions & 0 deletions src/cmd/hive/gfi_wire_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,63 @@ func TestGFICandidatesIncludeLabelledFilteredRows(t *testing.T) {
}
}

// Rows set aside because a pull request covers them (claimed_by_pr) that
// still wear the label reach the sweep marked HasLinkedPR, so it withdraws
// them (projectbluefin/website#1031); a relay contributor's or person's
// claim rides along so the label stays (gfi.Sweeper.Convert). Unlabelled
// covered rows are not candidates.
func TestGFICandidatesHandCoveredRowsToSweep(t *testing.T) {
res := &github.ActionableResult{
WorkDetailsByRepo: map[string]github.RepoWorkDetails{
"widgets": {Issues: []github.RepoWorkIssue{
{Repo: "widgets", Number: 1031, Labels: []string{"good first issue", "help wanted", "stage/040-covered-by-pr"}, Bucket: "claimed_by_pr", Reason: "Open external PR #1040 covers this issue"},
{Repo: "widgets", Number: 5, Labels: []string{"stage/040-covered-by-pr"}, Bucket: "claimed_by_pr"},
{Repo: "widgets", Number: 6, Labels: []string{"good first issue"}, Bucket: "claimed_by_pr", ClaimKind: string(claims.KindContributor), ClaimedBy: "newcomer"},
{Repo: "widgets", Number: 7, Labels: []string{"good first issue"}, Bucket: "claimed_by_pr", ClaimKind: string(claims.KindAgent), ClaimedBy: "scanner"},
}},
},
}
cands, labelled := gfiCandidates("acme", res, nil)
if len(cands) != 3 || labelled["acme/widgets#5"] {
t.Fatalf("cands %+v labelled %v", cands, labelled)
}
byNum := map[int]gfi.Candidate{}
for _, c := range cands {
byNum[c.Number] = c
}
if c := byNum[1031]; !c.HasLinkedPR || c.ClaimedBy != "" || len(c.Labels) != 3 {
t.Fatalf("covered row %+v", c)
}
if c := byNum[6]; !c.HasLinkedPR || c.ClaimedBy != "newcomer" {
t.Fatalf("contributor-claimed covered row %+v", c)
}
if c := byNum[7]; !c.HasLinkedPR || c.ClaimedBy != "" {
t.Fatalf("agent-claimed covered row %+v", c)
}
d := gfi.Score(byNum[1031], gfi.Policy{}, time.Now())
if d.Skip != gfi.SkipLinkedPR || !gfi.Withdrawable(d.Skip) {
t.Fatalf("covered row decision %+v", d)
}
if d := gfi.Score(byNum[6], gfi.Policy{}, time.Now()); d.Skip != "claimed" || gfi.Withdrawable(d.Skip) {
t.Fatalf("claimed covered row decision %+v", d)
}
}

// The sweep never advertises what the relay refuses: the policy carries
// hub.contribute_skip_labels (`needs-triage` by default).
func TestGFISweepOptionsCarryRelaySkip(t *testing.T) {
opts := gfiSweepOptions(&config.Config{}, nil, slog.New(slog.DiscardHandler))
if opts.Policy.RelaySkip == nil {
t.Fatal("RelaySkip not wired")
}
if l, ok := opts.Policy.RelaySkip([]string{"kind/bug", "needs-triage"}); !ok || l != "needs-triage" {
t.Fatalf("needs-triage not matched: %q %v", l, ok)
}
if _, ok := opts.Policy.RelaySkip([]string{"kind/bug", "size/S"}); ok {
t.Fatal("plain labels matched")
}
}

// gfiFakeGitHub serves the handful of endpoints the sweep and release touch.
type gfiFakeGitHub struct {
mu sync.Mutex
Expand Down
25 changes: 23 additions & 2 deletions src/docs/good-first-issue.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,12 +82,13 @@ Gates, in order; the first failure is the `gfi skip reason=…` logged:
|---|---|
| Pull request wearing the issue shape | `pull-request` |
| Live claimant (`hive:claim`, assignee) | `claimed`, `assigned` |
| An open PR already references the issue | `linked-pr` |
| An open PR already references the issue, or the enumeration set it aside because a pull request covers it (a `claimed_by_pr` row that still wears the label) | `linked-pr` |
| Hard-suppress label (`needs-human`, `stage/045-needs-decision`, a pre-045 `stage/085-needs-decision`, `needs-spec`, or the retired `needs-direction` / `needs-decision`) — always excluded, whatever `exclude_labels` says; `needs-human` next to `approved-direction` still excludes ([#12680](https://github.com/hivecommons/hive/issues/12680)) | `hard-suppress:<label>` |
| Any `hive/claimed-by-*` label (always excluded) | `excluded-label:<label>` |
| Excluded label (`kind/epic`, `epic`, `meta`, `meta-tracker`, `tracker`, `roadmap`, `security`, `blocked`, `hold`, `wontfix`, `duplicate`, `hive/in-progress`, `hive/claimed-by-*`, the hive's own `hive/advisory` / `hive/selfreport` / `hive/sentinel` / `hive/fleet` reports, …) | `excluded-label:<label>` |
| Operations tracking issue — the body carries `<!-- hive:ops-tracking -->` (the promote-stable workflow stamps its emergency follow-up issue with it), or the title/body uses soak-checklist phrasing ("24h after promotion", "post-hoc soak", "promote-stable") — a maintainer's checklist, not a code change ([#13267](https://github.com/hivecommons/hive/issues/13267)) | `ops-tracking:marker`, `ops-tracking:soak-checklist` |
| Time-gated — the body carries `<!-- hive:recheck-after <RFC3339> -->`, so nothing on it can be completed before the deadline | `time-gated` |
| A label the contributor relay refuses to hand out, matched by `hub.contribute_skip_labels` (`needs-triage`, `epic`, `tracking`, `discussion`, `question` and the needs-decision labels by default; glob patterns allowed). Checked after the gates above, so `blocked` and `tracking` (also in the default set) still withdraw. The welcome comment's claim link would lead nowhere | `relay-skip:<label>` |
| Title starts with `Epic`, `Tracking`, `RFC`, `Proposal`, `Umbrella`, `Hive Advisory Report`, … after leading emoji, `[tags]` and punctuation are stripped, or contains the word `epic`, `rfc`, `umbrella` or `meta` | `title:<word>` |
| Title mentions security work (`security`, `vulnerability`, `CVE-…`, `exploit`, `XSS`, `CSRF`, `RCE`, `injection`) even without a security label | `title:security` |
| Younger than `min_age` (default 1h) | `too-fresh` |
Expand Down Expand Up @@ -214,11 +215,31 @@ arrived without one, a single correction is posted):
```

Softer rejections (too fresh, low score, an epic a maintainer labelled by
hand) leave a hand-applied label alone. Issues the enumeration filtered out
hand) leave a hand-applied label alone. So does `relay-skip:<label>`: triage
adds and removes `needs-triage` all the time, and a withdrawal is permanent,
so an advertised issue that later gains a relay-skip label keeps its
invite. Issues the enumeration filtered out
(blocked, held, parked) that still wear the label are included in the pass
for this purpose only. The event logs as `gfi withdraw issue=… reason=…`
and audits as `gfi-withdraw`.

### Withdraw when a pull request covers the issue

A labelled issue that a pull request now covers (`linked-pr`, or the
`stage/040-covered-by-pr` label) is withdrawn the same way, whoever opened
the PR. The enumeration sets such an issue aside as a `claimed_by_pr` row,
and the sweep is handed those rows while they still wear the label. The
welcome comment is edited to:

```markdown
<!-- hive:gfi superseded=true -->
~~Good first issue~~ — **withdrawn** by <hive>: a pull request now covers this issue, so it is no longer open to new contributors. The `good first issue` and `help wanted` labels have been removed (<RFC3339>). Other issues open to new contributors are listed on the relay page: <public_url>/contribute
```

The exception is the outcome the label exists for: when a relay contributor
or a person claimed the issue and opened the PR, the label stays until the
issue closes and the claim counts as a conversion.

## Metrics

Structured logs: `gfi select issue=… score=… reasons=… claim_url=…`,
Expand Down
142 changes: 142 additions & 0 deletions src/pkg/gfi/covered_relayskip_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
package gfi

import (
"context"
"strings"
"testing"
)

// relaySkipNeedsTriage stands in for hub.contribute_skip_labels with the
// labels the default set shares with the GFI gates (`blocked`, `tracking`)
// plus `needs-triage`.
func relaySkipNeedsTriage(labels []string) (string, bool) {
for _, l := range labels {
switch strings.ToLower(strings.TrimSpace(l)) {
case "needs-triage", "blocked", "tracking":
return l, true
}
}
return "", false
}

func TestScoreRelaySkip(t *testing.T) {
p := Policy{RelaySkip: relaySkipNeedsTriage}
c := good()
c.Labels = append(c.Labels, "needs-triage")
if d := Score(c, p, now); d.Eligible || d.Skip != SkipRelaySkip+":needs-triage" {
t.Fatalf("needs-triage: %+v", d)
}
if d := Score(c, Policy{}, now); !d.Eligible {
t.Fatalf("no matcher, no relay gate: %+v", d)
}
if d := Score(good(), p, now); !d.Eligible {
t.Fatalf("control: %+v", d)
}
// The withdrawable gates still come first: `blocked` is in the relay's
// default skip set too, and must keep withdrawing.
c = good()
c.Labels = append(c.Labels, "blocked", "needs-triage")
if d := Score(c, p, now); d.Skip != "excluded-label:blocked" || !Withdrawable(d.Skip) {
t.Fatalf("blocked: %+v", d)
}
}

func TestWithdrawableCoveredAndRelaySkip(t *testing.T) {
for _, s := range []string{SkipLinkedPR, "excluded-label:stage/040-covered-by-pr", "excluded-label:Stage/040-Covered-By-PR"} {
if !Withdrawable(s) {
t.Errorf("%q should withdraw", s)
}
}
for _, s := range []string{SkipRelaySkip + ":needs-triage", SkipRelaySkip + ":question", "excluded-label:stage/030-pr-in-progress"} {
if Withdrawable(s) {
t.Errorf("%q should not withdraw", s)
}
}
}

// projectbluefin/website#1031: advertised at stage/010, then a pull request
// covered it. The next sweep takes both labels off and edits the welcome
// comment to say a PR covers it, without calling it "not newcomer work".
func TestSweepWithdrawsIssueAPullRequestCovers(t *testing.T) {
forge := newFakeForge()
s := NewSweeper()
var events []Event
opts := quietOpts()
opts.Audit = func(e Event) { events = append(events, e) }

c := good()
c.Labels = append([]string{Label, HelpWantedLabel}, c.Labels...)
c.HasLinkedPR = true
forge.comments[c.Key()] = []string{Marker + "\n### 🌱 Good first issue"}

res := s.Sweep(context.Background(), forge, []Candidate{c}, opts)
if len(res.Withdrawn) != 1 || res.Skipped[SkipLinkedPR] != 1 || len(res.Selected) != 0 || res.Errors != 0 {
t.Fatalf("result %+v", res)
}
if got := strings.Join(forge.removed[c.Key()], ","); got != Label+","+HelpWantedLabel {
t.Fatalf("removed %q", got)
}
if n := forge.commentCount(c.Repo, c.Number); n != 1 {
t.Fatalf("comment count %d (must edit, not add)", n)
}
body := forge.comments[c.Key()][0]
if !strings.Contains(body, SupersededMarker) || !strings.Contains(body, "a pull request now covers this issue, so it is no longer open to new contributors") || !strings.Contains(body, "https://hive.example/contribute") {
t.Fatalf("comment %q", body)
}
if strings.Contains(body, "Sorry for the noise") || strings.Contains(body, "not open to new contributors —") {
t.Fatalf("covered note reuses the not-newcomer-work wording: %q", body)
}
if len(events) != 1 || events[0].Action != "withdraw" || events[0].Reason != SkipLinkedPR {
t.Fatalf("events %+v", events)
}

// The covered stage label alone withdraws the same way.
staged := good()
staged.Number = 1032
staged.Labels = append([]string{Label}, "stage/040-covered-by-pr")
if res := s.Sweep(context.Background(), forge, []Candidate{staged}, opts); len(res.Withdrawn) != 1 {
t.Fatalf("stage/040: %+v", res)
}
if body := forge.comments[staged.Key()][0]; !strings.Contains(body, "a pull request now covers this issue") {
t.Fatalf("stage/040 comment %q", body)
}
}

// A relay contributor (or person) who claimed the issue and opened the PR is
// the outcome the label exists for: it stays until the issue closes.
func TestSweepLeavesClaimedCoveredIssueAlone(t *testing.T) {
forge := newFakeForge()
s := NewSweeper()
c := good()
c.Labels = append([]string{Label, HelpWantedLabel}, c.Labels...)
c.HasLinkedPR = true
c.ClaimedBy = "newcomer"
res := s.Sweep(context.Background(), forge, []Candidate{c}, quietOpts())
if len(res.Withdrawn) != 0 || len(forge.removed[c.Key()]) != 0 || res.Skipped["claimed"] != 1 {
t.Fatalf("claimed covered issue withdrawn: %+v removed=%v", res, forge.removed[c.Key()])
}
}

// An issue wearing a relay-skip label is never advertised; one already
// advertised that later gains it keeps the invite (triage flaps the label).
func TestSweepRelaySkipNeverSelectsNorWithdraws(t *testing.T) {
forge := newFakeForge()
s := NewSweeper()
opts := quietOpts()
opts.Policy.RelaySkip = relaySkipNeedsTriage

untriaged := good()
untriaged.Labels = append(untriaged.Labels, "needs-triage")
res := s.Sweep(context.Background(), forge, []Candidate{untriaged}, opts)
if len(res.Selected) != 0 || res.Skipped[SkipRelaySkip+":needs-triage"] != 1 || forge.commentCount(untriaged.Repo, untriaged.Number) != 0 {
t.Fatalf("untriaged issue advertised: %+v", res)
}

advertised := good()
advertised.Number = 1688
advertised.Labels = append([]string{Label, HelpWantedLabel, "needs-triage"}, advertised.Labels...)
res = s.Sweep(context.Background(), forge, []Candidate{advertised}, opts)
if len(res.Withdrawn) != 0 || len(forge.removed[advertised.Key()]) != 0 {
t.Fatalf("relay-skip withdrew an advertised issue: %+v removed=%v", res, forge.removed[advertised.Key()])
}
}
33 changes: 32 additions & 1 deletion src/pkg/gfi/gfi.go
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,13 @@ const (
// ReasonClaimedByHive is the release reason when a hive agent started on
// the issue.
ReasonClaimedByHive = "claimed-by-hive"

// SkipLinkedPR is the Decision.Skip reason for an issue a pull request
// already covers (Candidate.HasLinkedPR).
SkipLinkedPR = "linked-pr"
// SkipRelaySkip prefixes the Decision.Skip reason for an issue wearing a
// label the contributor relay refuses (Policy.RelaySkip).
SkipRelaySkip = "relay-skip"
)

// AlwaysExcludeLabels disqualify an issue whatever Policy.ExcludeLabels or
Expand Down Expand Up @@ -214,6 +221,10 @@ type Policy struct {
ExcludeLabels []string
// HardSuppressLabels are the hive's escalation labels; always excluded.
HardSuppressLabels []string
// RelaySkip, when set, reports the first label the contributor relay
// refuses to hand out (hub.contribute_skip_labels). Such an issue is
// never advertised: its welcome comment's claim link would lead nowhere.
RelaySkip func(labels []string) (string, bool)
}

// Normalized fills zero fields with the defaults.
Expand Down Expand Up @@ -279,7 +290,7 @@ func Score(c Candidate, p Policy, now time.Time) Decision {
case len(c.Assignees) > 0:
return skip(d, "assigned")
case c.HasLinkedPR:
return skip(d, "linked-pr")
return skip(d, SkipLinkedPR)
}
for _, l := range AlwaysExcludeLabels {
if labels[l] {
Expand Down Expand Up @@ -310,6 +321,13 @@ func Score(c Candidate, p Policy, now time.Time) Decision {
if _, ok := ParseRecheckAfter(c.Body); ok {
return skip(d, SkipTimeGated)
}
// After every withdrawable gate: the relay's default skip set also lists
// `blocked` and `tracking`, and those must still withdraw.
if p.RelaySkip != nil {
if l, ok := p.RelaySkip(c.Labels); ok {
return skip(d, SkipRelaySkip+":"+l)
}
}
title := NormalizeTitle(c.Title)
for _, prefix := range epicTitlePrefixes {
if strings.HasPrefix(title, prefix) {
Expand Down Expand Up @@ -847,6 +865,19 @@ func WithdrawnComment(c Candidate, reason string, l Links, at time.Time) string
if hive == "" {
hive = "this hive"
}
if coveredByPR(reason) {
// It was newcomer work; someone took it. No "not newcomer work"
// correction and no apology.
var b strings.Builder
b.WriteString(SupersededMarker + "\n")
fmt.Fprintf(&b, "~~Good first issue~~ — **withdrawn** by %s: a pull request now covers this issue, so it is no longer open to new contributors. The `%s` and `%s` labels have been removed (%s).",
hive, Label, HelpWantedLabel, at.UTC().Format(time.RFC3339))
if origin := strings.TrimRight(strings.TrimSpace(l.Origin), "/"); origin != "" {
fmt.Fprintf(&b, " Other issues open to new contributors are listed on the relay page: %s/contribute", origin)
}
b.WriteString("\n")
return b.String()
}
var why string
switch {
case strings.HasPrefix(reason, SkipTracking+":"):
Expand Down
Loading
Loading