Skip to content

Commit a13fc0b

Browse files
exploreriiiadityashirsatrao007Copilot
authored
docs: gfi guidelines (hiero-ledger#1133)
Signed-off-by: Aditya Shirsatrao <[email protected]> Signed-off-by: adityashirsatrao007 <[email protected]> Signed-off-by: Aditya <[email protected]> Signed-off-by: exploreriii <[email protected]> Co-authored-by: adityashirsatrao007 <[email protected]> Co-authored-by: Copilot <[email protected]>
1 parent dc3614d commit a13fc0b

File tree

6 files changed

+454
-3
lines changed

6 files changed

+454
-3
lines changed

‎.github/ISSUE_TEMPLATE/01_good_first_issue.yml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ body:
99
value: |
1010
---
1111
## **Thanks for contributing!** 😊
12-
12+
1313
We truly appreciate your time and effort. If this is your first open-source contribution, welcome!
1414
This template is designed to help you create a Good First Issue (GFI) : a small, well-scoped task that helps new contributors learn the codebase and workflow.
1515
---
@@ -55,7 +55,8 @@ body:
5555
> - Changes to DLT functionality, like `to_proto` and `from_proto`
5656
> - Anything requiring knowledge of multiple areas of the codebase
5757
>
58-
> 📖 *For a more detailed explanation, refer to `docs/maintainers/good_first_issues_guidelines.md`.*
58+
> 📖 *For a more detailed explanation, refer to:
59+
> [`docs/maintainers/good_first_issues_guidelines.md`](docs/maintainers/good_first_issues_guidelines.md).*
5960
6061
- type: textarea
6162
id: issue

‎.github/ISSUE_TEMPLATE/04_good_first_issue_candidate.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,8 @@ body:
6363
> - Changes to DLT functionality, like `to_proto` and `from_proto`
6464
> - Anything requiring knowledge of multiple areas of the codebase
6565
>
66-
> 📖 *For a more detailed explanation, refer to `docs/maintainers/good_first_issues_guidelines.md`.*
66+
> 📖 *For a more detailed explanation, refer to:
67+
> [`docs/maintainers/good_first_issue_candidate_guidelines.md`](docs/maintainers/good_first_issue_candidate_guidelines.md).*
6768
6869
- type: textarea
6970
id: issue

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
1515
- Codecov workflow
1616
- Added unit tests for `key_format.py` to improve coverage.
1717
- Fix inactivity bot execution for local dry-run testing.
18+
- Added Good First Issue candidate guidelines documentation (`docs/maintainers/good_first_issue_candidate_guidelines.md`) and Good First Issues guidelines documentation (`docs/maintainers/good_first_issues_guidelines.md`) (#1066)
1819
- Added documentation: "Testing GitHub Actions using Forks" (`docs/sdk_developers/training/testing_forks.md`).
1920
- Unified the inactivity-unassign bot into a single script with `DRY_RUN` support, and fixed handling of cross-repo PR references for stale detection.
2021
- Added unit tests for `SubscriptionHandle` class covering cancellation state, thread management, and join operations.

‎docs/maintainers/good_first_issue_candidate_guidelines.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# Good First Issue — Candidate Guidelines
2+
3+
This document explains the purpose of the **`good first issue: candidate`** label, when to use it, and when an issue should be promoted to a full **Good First Issue**.
4+
5+
## Table of Contents
6+
7+
- [Why We Use a "Candidate" Label](#-why-we-use-a-candidate-label)
8+
- [When to Use the Candidate Label](#️-when-to-use-good-first-issue-candidate)
9+
- [What a Candidate Is NOT](#-what-a-candidate-is-not)
10+
- [Promoting a Candidate to GFI](#-promoting-a-candidate-to-gfi)
11+
- [Workflow Summary](#-workflow-summary)
12+
- [Important Considerations](#important-considerations)
13+
14+
---
15+
16+
## 🎯 Why We Use a "Candidate" Label
17+
18+
Labeling an issue as a **Good First Issue (GFI)** signals to new contributors that the issue is:
19+
20+
- ✅ **Well-scoped** — clear boundaries and deliverables
21+
- ✅ **Low risk** — minimal chance of breaking changes
22+
- ✅ **Clearly defined** — unambiguous requirements
23+
- ✅ **Ready to be picked up** — with minimal guidance needed
24+
25+
However, **not all issues start in that state**.
26+
27+
The **`good first issue: candidate`** label exists to:
28+
29+
| Purpose | Description |
30+
|---------|-------------|
31+
| 🚫 **Avoid premature labeling** | Prevent issues from being labeled as GFIs before they're ready |
32+
| 🔍 **Allow refinement time** | Give maintainers space to clarify scope and requirements |
33+
| 📊 **Set accurate expectations** | Ensure new contributors know exactly what to do |
34+
| 📋 **Create a clear pipeline** | Establish a workflow for curating high-quality GFIs |
35+
36+
This approach helps us prioritize **quality over quantity** when advertising beginner-friendly work.
37+
38+
---
39+
40+
## 🏷️ When to Use `good first issue: candidate`
41+
42+
Apply the **candidate** label when an issue:
43+
44+
### ✅ Fits the General Criteria
45+
46+
- *Might* be suitable as a GFI based on initial assessment
47+
- Fits within the [allowed categories](./good_first_issues_guidelines.md#allowed-categories) of GFI work
48+
- Appears to be small in scope and low risk
49+
50+
### ⏳ Still Needs Work
51+
52+
- **Needs clarification** — requirements are ambiguous or incomplete
53+
- **Needs refinement** — scope could be narrowed or better defined
54+
- **Needs confirmation** — maintainer review required to verify suitability
55+
- **Needs acceptance criteria** — clear success conditions not yet defined
56+
57+
### 📝 Example Scenarios
58+
59+
| Scenario | Why Use Candidate? |
60+
|----------|-------------------|
61+
| User reports a documentation gap | Needs scoping to determine exact changes required |
62+
| Bug in example code identified | Need to confirm it's isolated and straightforward to fix |
63+
| Type annotation improvement suggested | Need to verify it doesn't affect runtime behavior |
64+
| Test assertion missing | Need to confirm it extends existing tests only |
65+
66+
---
67+
68+
## 🚦 What a Candidate Is NOT
69+
70+
The **candidate** label should **NOT** be used for:
71+
72+
### ❌ Large or Cross-Cutting Changes
73+
74+
Issues that span multiple modules, packages, or require architectural understanding.
75+
76+
### ❌ Core Protocol or SDK Logic
77+
78+
Changes to:
79+
- `to_proto` / `from_proto` methods
80+
- Serialization/deserialization logic
81+
- Network or wire-level behavior
82+
83+
### ❌ Exploratory or Investigative Work
84+
85+
Issues where the solution path is unclear or requires research.
86+
87+
### ❌ Blocked Issues
88+
89+
Issues that depend on external decisions, other PRs, or upstream changes.
90+
91+
---
92+
93+
> ⚠️ **Important:** If an issue clearly does *not* meet GFI criteria, it should **not** be labeled as a candidate either. The candidate label is for issues that *might* qualify, not for issues that definitely won't.
94+
95+
---
96+
97+
## ✨ Promoting a Candidate to GFI
98+
99+
A candidate should be promoted to a full **Good First Issue** when:
100+
101+
### Readiness Checklist
102+
103+
- [ ] **Clear description** — the problem and solution are well-defined
104+
- [ ] **Scoped appropriately** — changes are localized and low-risk
105+
- [ ] **Acceptance criteria defined** — clear conditions for success
106+
- [ ] **Documentation linked** — relevant guides are referenced
107+
- [ ] **No blockers** — no dependencies on other work
108+
- [ ] **Maintainer approved** — a maintainer has reviewed and confirmed suitability
109+
110+
### Promotion Process
111+
112+
1. **Review the candidate issue** against [GFI guidelines](./good_first_issues_guidelines.md)
113+
2. **Add missing details** — clarify requirements, add acceptance criteria
114+
3. **Remove `good first issue: candidate`** label
115+
4. **Add `Good First Issue`** label
116+
5. **Optionally notify** in comments that the issue is ready for contributors
117+
118+
---
119+
120+
## 📊 Workflow Summary
121+
122+
```
123+
┌─────────────────────────────────────────────────────────────┐
124+
│ Issue Created │
125+
└─────────────────────────────────────────────────────────────┘
126+
│
127+
▼
128+
┌─────────────────────────────────────────────────────────────┐
129+
│ Initial Assessment by Maintainer │
130+
│ │
131+
│ Is this potentially a Good First Issue? │
132+
│ │
133+
│ • Small scope? │
134+
│ • Low risk? │
135+
│ • Fits allowed categories? │
136+
└─────────────────────────────────────────────────────────────┘
137+
│
138+
┌───────────────┼───────────────┐
139+
│ │ │
140+
▼ ▼ ▼
141+
┌────────┐ ┌──────────┐ ┌──────────┐
142+
│ No │ │ Maybe │ │ Yes │
143+
└────────┘ └──────────┘ └──────────┘
144+
│ │ │
145+
▼ ▼ ▼
146+
┌─────────────────┐ ┌───────────────┐ ┌───────────────┐
147+
│ Label normally │ │ Label as │ │ Label as │
148+
│ (not GFI) │ │ `candidate` │ │ Good First │
149+
│ │ │ │ │ Issue │
150+
└─────────────────┘ └───────────────┘ └───────────────┘
151+
│
152+
▼
153+
┌─────────────────┐
154+
│ Refine & Review │
155+
│ │
156+
│ • Add details │
157+
│ • Define scope │
158+
│ • Set criteria │
159+
└─────────────────┘
160+
│
161+
▼
162+
┌─────────────────┐
163+
│ Promote to GFI │
164+
│ when ready │
165+
└─────────────────┘
166+
```
167+
168+
---
169+
170+
## Important Considerations
171+
172+
### Why This Matters
173+
174+
1. **Good First Issues are automatically promoted** by GitHub and Hiero, making them highly visible to potential contributors worldwide
175+
176+
2. **New contributors trust the GFI label** — they expect issues to be ready and achievable
177+
178+
3. **Poorly scoped GFIs waste contributor time** — and can discourage future contributions
179+
180+
4. **Quality GFIs build community** — successful first contributions lead to long-term contributors
181+
182+
### Best Practices
183+
184+
| Do | Don't |
185+
|----|-------|
186+
| ✅ Use candidate for uncertain issues | ❌ Rush issues to GFI status |
187+
| ✅ Take time to refine candidates | ❌ Label obviously unsuitable issues as candidates |
188+
| ✅ Add clear acceptance criteria before promotion | ❌ Promote candidates without review |
189+
| ✅ Link to relevant documentation | ❌ Assume contributors know the codebase |
190+
191+
---
192+
193+
## Additional Resources
194+
195+
- [Good First Issue Guidelines](./good_first_issues_guidelines.md) — what qualifies as a GFI
196+
- [Contributing Guide](../../CONTRIBUTING.md) — how to contribute
197+
- [DCO Signing Guide](../sdk_developers/signing.md) — commit signing requirements
198+
- [Discord Community](../discord.md) — get help from the community
199+
- [Community Calls](https://zoom-lfx.platform.linuxfoundation.org/meetings/hiero?view=week) — weekly office hours

‎docs/maintainers/good_first_issues.md‎

Whitespace-only changes.

0 commit comments

Comments
 (0)