doc: Remove good_first_issue.yml, Reword "Getting started" section #35400

maflcko commented at 7:13 AM on May 28, 2026: member

IIUC, the good-first-issue label and template were meant to make it easier for completely new contributors to get started with something simple. However, I don't think the label and issue template are applicable anymore:

There are currently no issues with this label, and directing people toward an empty list seems pointless.
Historically the issue and label has been used rarely. 2026: once, 2025 twice, 2024 thrice. Source: https://github.com/bitcoin/bitcoin/issues?q=state%3Aclosed%20is%3Aissue%20label%3A%22good%20first%20issue%22
The template has been mis-used, according to #35399

Fix all issues by removing it, since it is clear that it is no longer actively used, nor applicable and possibly a net-negative overall.

Of course, regular devs are still free to open issues of this kind as a normal issue, if they wish. However, having the template for this in this repo and tracking it via a label doesn't seem useful.

Since removing the template and label requires rewriting the "Getting Started" section in CONTRIBUTING.md, I went ahead and also removed the mention of Up for grabs as good things for newcomers to work on. I don't recall the last new contributor that picked something up successfully. Also, Up for grabs is usually stuff that people lost interest in, or is no longer relevant.

Instead I've added a sentence to encourage new contributors to help with critical and broad review, which will naturally guide them to good first follow-up issues to work on.

Meta: I know this topic can be subjective and offer bike-shed potential, but I am happy to iterate a bit on this for a few days.

doc: Remove good_first_issue.yml fab5733f5d

DrahtBot renamed this:
~~doc: Remove good_first_issue.yml, Reword "Getting started" section~~
doc: Remove good_first_issue.yml, Reword "Getting started" section
on May 28, 2026

DrahtBot added the label Docs on May 28, 2026

DrahtBot commented at 7:13 AM on May 28, 2026: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/35400.

Reviews

See the guideline for information on the review process.

Type	Reviewers
ACK	stickies-v, sedited, danielabrozzoni, darosior, furszy, winterrdog
Concept ACK	fanquake

If your review is incorrectly listed, please copy-paste <code></code> into the comment that the bot should ignore.

Conflicts

Reviewers, this pull request conflicts with the following ones:

#35386 (doc: add an AI contribution policy by willcl-ark)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

DrahtBot added the label CI failed on May 28, 2026

DrahtBot removed the label CI failed on May 28, 2026

fanquake commented at 9:03 AM on May 28, 2026: member

Concept ACK

in CONTRIBUTING.md:27 in fa45104aa2

  23 | @@ -24,33 +24,17 @@ as a new contributor. It also will teach you much more about the code and
  24 |  process than opening pull requests. Please refer to the [peer review](#peer-review)
  25 |  section below.
  26 |  
  27 | +The bottleneck of the project is peer review and testing, not writing code. A

stickies-v commented at 10:18 AM on May 28, 2026:

This overlaps quite a bit with the previous paragraph. Suggested merging:

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d77e4ec529..0505b6b1b7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -19,15 +19,11 @@ Getting Started
 
 New contributors are very welcome and needed.
 
-Reviewing and testing is highly valued and the most effective way you can contribute
-as a new contributor. It also will teach you much more about the code and
-process than opening pull requests. Please refer to the [peer review](#peer-review)
-section below.
-
-The bottleneck of the project is peer review and testing, not writing code. A
-critical and broad review of a pull request may sometimes uncover unrelated
-issues and follow-ups. So helping with review instead of opening a pull request
-may naturally expose you to good first issues to work on.
+In-depth reviewing and testing are the bottleneck of the project, and are the
+most effective way anyone can start to contribute. It will teach you much more
+about the code and process than opening pull requests, and may help you uncover
+related issues and follow-ups to contribute code for. Please refer to the [peer
+review](#peer-review) section below.
 
 Before you start contributing, familiarize yourself with the Bitcoin Core build
 system and tests. Refer to the documentation in the repository on how to build

</details>

stickies-v approved

stickies-v commented at 10:18 AM on May 28, 2026: contributor

ACK fa45104aa29d640cd8cc3db9b3c667b191929d69

DrahtBot requested review from fanquake on May 28, 2026

danielabrozzoni commented at 10:21 AM on May 28, 2026: member

Concept ACK on removing the good first issue label. I think it's useful to nudge new contributors towards reviewing PRs and explain how naturally work will come up during PR review.

I'm a bit more hesitant about removing the "Up for grabs" mention entirely. I picked up #32740 as a new-ish contributor after a few months working on Core, so I wasn't exactly just getting started, and I wouldn't have known about the label without its mention in CONTRIBUTING.md.

I agree it doesn't belong in the "Getting started" section, since some experience is needed to judge whether an issue is worth picking up. But I wonder if there's another place where it could be mentioned.

doc: Reword the Getting-Started section

Explain how to find good first issues to work on.

Also, remove the mention of up-for-grabs for new contributors, because
up-for-grabs is usually stuff that people lost interest in and is often
no longer relevant.

fa51f37f18

maflcko force-pushed on May 28, 2026

maflcko commented at 11:36 AM on May 28, 2026: member

I'm a bit more hesitant about removing the "Up for grabs" mention entirely. I picked up #32740 as a new-ish contributor after a few months working on Core, so I wasn't exactly just getting started, and I wouldn't have known about the label without its mention in CONTRIBUTING.md.

I agree it doesn't belong in the "Getting started" section, since some experience is needed to judge whether an issue is worth picking up. But I wonder if there's another place where it could be mentioned.

Good point. Maybe in a later section? Happy to push a diff if someone writes one :)

stickies-v commented at 11:42 AM on May 28, 2026: contributor

ACK fa51f37f1800d3886172fbc4c418685530011e2d

DrahtBot requested review from danielabrozzoni on May 28, 2026

sedited approved

sedited commented at 11:57 AM on May 28, 2026: contributor

ACK fa51f37f1800d3886172fbc4c418685530011e2d

danielabrozzoni commented at 1:00 PM on May 28, 2026: member

The up for grabs part could be moved into the Contributor Workflow section:

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0505b6b1b7..63b62abde2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -58,6 +58,12 @@ The codebase is maintained using the "contributor workflow" where everyone
 without exception contributes patch proposals using "pull requests" (PRs). This
 facilitates social contribution, easy testing and peer review.
 
+If you're looking for something to work on, the
+[up for grabs](https://github.com/bitcoin/bitcoin/issues?q=label%3A%22Up+for+grabs%22)
+label marks pull requests that were previously being worked on but are no longer
+actively pursued. Note that some may no longer be applicable, so consider
+leaving a comment first to confirm.
+
 Pull request authors must fully and confidently understand their own changes
 and must have tested them. Contributors should mention which tests cover their
 changes, or include the manual steps they used to confirm the change.

However, I think it's also ok as-is, and I don't want to hold this up :)

ACK fa51f37f1800d3886172fbc4c418685530011e2d

stickies-v commented at 1:07 PM on May 28, 2026: contributor

The up for grabs part could be moved into the Contributor Workflow section:

I'd prefer keeping that for a separate PR, because I strongly disagree with it. People opening PRs because they want something to work on is absolutely not something we should encourage in a review-constrained repository where we're trying to guide people to work on important projects rather than busywork (fully appreciating that yes, especially as a newcomer, this can be a easy way to get started etc).

danielabrozzoni commented at 1:19 PM on May 28, 2026: member

Ah, I see your point. I accidentally worded it in a way that seems to encourage people towards writing code for its own sake.

Well, I'm ok with the up for grabs part being removed :)

darosior commented at 2:05 PM on May 28, 2026: member

ACK fa51f37f1800d3886172fbc4c418685530011e2d

furszy commented at 2:13 PM on May 28, 2026: member

ACK fa51f37f1800d3886172fbc4c418685530011e2d

winterrdog commented at 3:08 PM on May 28, 2026: none

ACK fa51f37f1800d3886172fbc4c418685530011e2d

fanquake merged this on May 28, 2026

fanquake closed this on May 28, 2026

maflcko deleted the branch on May 28, 2026