Expand self-assignment to help wanted issues after three merged pull requests #113

Overview

/assign works only on an issue labelled good first issue. An issue labelled help wanted alone
gets no guidance comment, and a contributor who asks for it gets no reply. Maintainers assign all of
those by hand.

Open help wanted issues to self-assignment for contributors with three or more merged pull
requests. New contributors keep good first issue as their route in.

Complexity: Medium
Target branch: main

Context

learningequality/kolibri#15549 is the case that prompted this. help wanted was added, the job ran,
and good-first-issue-comment.js:22 returned without posting, because it requires both labels.

The distinction exists to keep harder issues with contributors who finish things. A merge count
turns that into something measurable, so the label can open up without losing the intent.

help wanted is the parent label in practice. Across kolibri, studio and kolibri-design-system
there are no open issues carrying good first issue without help wanted. In closed history there
are 18, against 232 carrying both and 170 carrying help wanted alone.

Three places key on good first issue:

The rules after this change

good first issue wins when both are present, because it is the more permissive.

Every existing check still applies, in this order: the commenter is a contributor rather than a core
member or bot, the issue is open, it is not already assigned to someone else, and the contributor
holds fewer than MAX_ASSIGNED_ISSUES slots counting issues dropped inside ASSIGN_COOLDOWN_DAYS.

Clarifications

Which rejection wins. Someone below the threshold asking for a help wanted issue that is
already taken hits two reasons at once. "Already assigned" wins, because it is the more actionable
one and it is the earlier check today.

What the count measures. Merged pull requests anywhere in the organization, public only. The
threshold is calibrated against that measure. Restricting it to the community repos would give
lower counts and would need recalibrating.

Maintainers bypass all of it. Every rule here lives in the /assign path, so assigning by hand
still skips the threshold and the limit. That stays the escape hatch for an experienced contributor
you want on something before they reach three.

The Change

Count merged pull requests. Add a helper to scripts/utils.js that returns the number of merged
pull requests a contributor has authored in the organization, from one search call:

org:learningequality is:pr is:merged author:<login>

A deleted or renamed account returns 422 from that endpoint rather than a count. Treat that as zero
rather than failing the run.

Replace the label gate with the count. contributor-issue-comment.js:145 to 153 currently
refuses /assign without good first issue. It instead refuses when the issue carries only
help wanted and the contributor is below the threshold. Line 114 already covers an issue with
neither label.

Post guidance on help wanted. good-first-issue-comment.js:22 posts when help wanted is
present. The message depends on whether good first issue is there too.

Answer an assignment request. contributor-issue-comment.js:225 replies on a help wanted
issue as well, rather than staying silent.

Messages

• BOT_MESSAGE_GOOD_FIRST_ISSUE_GUIDANCE stays as it is, for an issue with good first issue.
• A new guidance message for help wanted alone. It says the issue is open for contribution, that
  self-assignment needs three merged pull requests, and that anyone below that should comment to
  ask, because a maintainer assigns those.
• A new decline for /assign below the threshold. It must name the threshold and the contributor's
  current count, and point them at good first issues. A decline with no number reads as arbitrary.
• BOT_MESSAGE_ASSIGN_NOT_GOOD_FIRST_ISSUE is replaced by that decline.

Why three

Merged pull requests across recent contributors outside the established cohort:

Three qualifies 8 of 24 and leaves 16 on the manual path. Two would qualify 13 and leave 11.

Three was chosen because the threshold can be lowered later without cost. Anyone who qualifies at
three also qualifies at two, so dropping it only adds people. Raising it takes self-assignment away
from contributors who already had it.

The count above is org-wide and public, which is what the threshold is calibrated against. A
per-repo measure would need recalibrating.

Dependency worth knowing

good first issue becomes the only on-ramp. If that queue runs dry, new contributors have no route
to their first three merges. A maintainer assigning by hand stays the escape hatch, as it is today.

Out of Scope

• Changing MAX_ASSIGNED_ISSUES or ASSIGN_COOLDOWN_DAYS.
• Weighting a merge by size. A merge is a merge.
• Relabelling the closed issues that carry good first issue alone.
• The welcome header in the issue body, which already appears on help wanted.

Acceptance Criteria

• Adding help wanted posts guidance that states the three merge rule.
• Adding good first issue posts the existing guidance, and only one guidance comment remains.
• /assign on a good first issue works for anyone, as today.
• /assign on a help wanted issue works at three or more merged pull requests.
• /assign on a help wanted issue below three declines, naming the threshold and the count.
• /assign on an issue with neither label still gets BOT_MESSAGE_ISSUE_NOT_OPEN.
• /assign on an issue assigned to someone else still gets BOT_MESSAGE_ALREADY_ASSIGNED, and
  that message wins over the threshold decline when both apply.
• The two issue limit and the cooldown still apply above the threshold.
• Asking to work on a help wanted issue gets a reply rather than silence.
• A login that no longer resolves counts as zero and does not fail the run.
• BOT_MESSAGE_ASSIGN_NOT_GOOD_FIRST_ISSUE is gone, and nothing references it.
• Tests cover each label state, and counts of 0, 2, 3 and a failed lookup.
• docs/community-automations.md describes the three label states.

Testing

Test in test-actions. See
testing the automations.
The cases need an account outside the organization.

1. Add help wanted to an issue. Expect guidance naming the three merge rule.
2. Add good first issue as well. Expect the existing guidance, and one comment rather than two.
3. Comment /assign from an account with fewer than three merges on a help wanted issue. Expect
   the decline, with the count.
4. Comment /assign on a good first issue from the same account. Expect assignment.
5. Comment /assign on an issue with neither label. Expect the not-open message.

References

• Replace $computedClass in the content viewers kolibri#15549 is the case that prompted this.
• Require an open pull request before a second issue assignment #104 gates a second assignment on an open pull request. That gate and the two issue limit hold the
  volume down above this threshold.
• Two /assign comments at once can both pass the assignment limit #107 fixes the race that lets two /assign comments both pass the limit.

AI usage

I used Claude Code to find why no comment was posted, trace every place the two labels gate
behaviour, and count merged pull requests across the recent contributor cohort. The threshold and
the rule are my decision.