Skip to content

Commit 7fae36b

Browse files
aceppaluniaceppaluni
authored
docs: Add GFI-Management and GFI-Frequency docs files (#1132)
Signed-off-by: aceppaluni <[email protected]>
1 parent e3d5578 commit 7fae36b

File tree

3 files changed

+256
-0
lines changed

3 files changed

+256
-0
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
99

1010

1111
### Added
12+
- Added Good First Issue (GFI) management and frequency documentation to clarify maintainer expectations and SDK-level GFI governance.
1213
- Added SDK-level Good First Issue (GFI) guidelines for maintainers to clarify what qualifies as a good first issue.
1314
- Codecov workflow
1415
- Added unit tests for `key_format.py` to improve coverage.

‎docs/GFI/GFI-Frequency.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Good First Issue (GFI) Frequency Guidelines
2+
3+
## Purpose
4+
5+
This document defines **how frequently Good First Issues (GFIs)** should be created and maintained for an SDK.
6+
7+
Clear expectations around GFI frequency help:
8+
- Maintain a healthy contributor pipeline
9+
- Prevent contributor overload or abandonment
10+
- Align GFI availability with maintainer capacity and review bandwidth
11+
12+
These guidelines are **SDK-specific** and may differ across SDKs depending on team size, activity, and release cadence.
13+
14+
---
15+
16+
## What Is GFI Frequency?
17+
18+
**GFI frequency** refers to the number of open, actively maintained Good First Issues an SDK aims to support over time.
19+
20+
This is not a hard requirement, but a **maintainer-defined target** that helps ensure:
21+
- Issues labeled as GFI receive timely responses
22+
- Contributors are not left waiting without feedback
23+
- Maintainers do not overcommit beyond their review capacity
24+
25+
---
26+
27+
## Recommended Frequency Models
28+
29+
Maintainers may choose one of the following models, or define a custom approach that fits their SDK.
30+
31+
### 1. Fixed Cadence
32+
33+
A predictable schedule for creating or refreshing GFIs.
34+
35+
**Examples:**
36+
- One GFI per month
37+
- One GFI every two weeks
38+
- Two GFIs per week
39+
40+
This model works well for SDKs with:
41+
- Stable maintainer availability
42+
- Regular contributor interest
43+
- Predictable release cycles
44+
45+
---
46+
47+
### 2. Capacity-Based (Burn Rate)
48+
49+
GFIs are created based on **maintainer capacity**, not time.
50+
51+
**Examples:**
52+
- Maintain 1–3 open GFIs at any given time
53+
- Only open a new GFI when an existing one is closed or inactive
54+
- Limit GFIs to what can be reviewed within a defined SLA (e.g., 5 business days)
55+
56+
This model works well for:
57+
- Small maintainer teams
58+
- Periods of high operational load
59+
- SDKs with fluctuating contributor demand
60+
61+
---
62+
63+
### 3. Hybrid Model
64+
65+
A combination of cadence and capacity.
66+
67+
**Examples:**
68+
- One GFI per month, up to a maximum of 3 open GFIs
69+
- Weekly GFI creation, paused when review backlog exceeds a threshold
70+
71+
---
72+
73+
## SDK-Specific Declaration
74+
75+
Each SDK is encouraged to **explicitly declare its GFI frequency policy**, for example:
76+
77+
```text
78+
This SDK aims to maintain up to two active Good First Issues at any given time,
79+
subject to maintainer availability.

‎docs/GFI/GFI-Management.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Good First Issue (GFI) Management Guidelines
2+
3+
## Purpose
4+
5+
This document describes **how Good First Issues (GFIs)** should be managed once they are created.
6+
7+
Clear management practices help:
8+
- Ensure GFIs remain welcoming and actionable
9+
- Provide consistent contributor experiences
10+
- Balance maintainer workload with community engagement
11+
12+
These guidelines focus on **maintainer responsibilities and discretion** and are intended to be applied at the **SDK level**.
13+
14+
---
15+
16+
## What Is GFI Management?
17+
18+
**GFI management** refers to the ongoing actions maintainers take to ensure that:
19+
- Issues labeled as `good first issue` remain suitable for new contributors
20+
- Contributors receive timely guidance and feedback
21+
- GFIs do not become stale, abandoned, or misleading
22+
23+
Management is not micromanagement; it is **lightweight stewardship**.
24+
25+
---
26+
27+
## GFI Lifecycle Overview
28+
29+
A Good First Issue typically moves through the following stages:
30+
31+
1. Identified as a potential GFI (GFIC — Good First Issue Candidate)
32+
2. Reviewed and labeled as a GFI
33+
3. Assigned or claimed by a contributor
34+
4. Actively supported through contribution
35+
5. Completed, relabeled, or closed
36+
37+
Not all GFIs must follow this exact flow, but clarity around expectations helps contributors succeed.
38+
39+
---
40+
41+
## Labeling and Promotion (GFIC → GFI)
42+
43+
Maintainers may use an intermediate **Good First Issue Candidate (GFIC)** state.
44+
45+
### Recommended Practices
46+
47+
- Use a `good first issue candidate` (or similar) label to flag potential GFIs
48+
- Promote an issue from GFIC → GFI once:
49+
- Scope and acceptance criteria are clear
50+
- The issue meets `GFI-guidelines.md`
51+
- Maintainer capacity exists to support it
52+
53+
Maintainers are not required to promote every GFIC to a GFI.
54+
55+
---
56+
57+
## Assignment and Claiming
58+
59+
Maintainers may choose how contributors engage with GFIs.
60+
61+
### Common Approaches
62+
63+
- Allow contributors to self-assign
64+
- Assign first-time contributors upon request
65+
- Limit the number of simultaneous GFI assignments per contributor
66+
67+
### Recommended Guidance
68+
69+
- Prefer assigning **one contributor per GFI**
70+
- Avoid long-term assignment without activity
71+
- Reclaim or unassign issues after prolonged inactivity, with a clear comment
72+
73+
This ensures fair access and avoids stalled issues.
74+
75+
---
76+
77+
## Mentorship and Support
78+
79+
Mentorship is encouraged but **not mandatory**.
80+
81+
### Examples of Supportive Management
82+
83+
- Answering clarification questions
84+
- Pointing contributors to relevant files or examples
85+
- Clarifying acceptance criteria
86+
- Suggesting incremental approaches
87+
88+
### What Is *Not* Expected
89+
90+
- Writing the solution for the contributor
91+
- Providing extensive code reviews beyond GFI scope
92+
- Guaranteeing real-time or synchronous support
93+
94+
Light guidance is often sufficient for a successful first contribution.
95+
96+
---
97+
98+
## Review Expectations (“Soft Review”)
99+
100+
Maintainers may choose to apply a **lighter review standard** for GFIs.
101+
102+
### Soft Review May Include
103+
104+
- Prioritizing clarity and correctness over optimization
105+
- Offering constructive, educational feedback
106+
- Allowing minor follow-up improvements after merge
107+
108+
### Still Required
109+
110+
- Correctness
111+
- Tests where applicable
112+
- Compliance with project standards
113+
114+
GFIs should be welcoming, not lower-quality.
115+
116+
---
117+
118+
## Maintainer Discretion and Control
119+
120+
Maintainers retain full control over:
121+
122+
- Labeling or removing the `good first issue` label
123+
- Assignment decisions
124+
- Pausing or closing GFIs
125+
- Adjusting management practices over time
126+
127+
Discretion allows maintainers to adapt to workload, contributor behavior, and project priorities.
128+
129+
---
130+
131+
## Transparency and Community Engagement
132+
133+
Maintainers are encouraged to:
134+
- Leave brief comments when relabeling or closing GFIs
135+
- Explain pauses or changes in availability
136+
- Encourage contributors to ask questions
137+
138+
Transparency builds trust and helps the community understand expectations.
139+
140+
---
141+
142+
## Updating GFI Management Practices
143+
144+
This document is intended to be **easy to update**.
145+
146+
Maintainers may:
147+
- Adjust management practices at any time
148+
- Experiment with different levels of mentorship or review
149+
- Align management with `GFI-frequency.md` and maintainer capacity
150+
151+
Updates should be treated as **process guidance**, not rigid policy.
152+
153+
---
154+
155+
## Relationship to Other GFI Documents
156+
157+
This document complements:
158+
- `GFI-guidelines.md` — what qualifies as a GFI
159+
- `GFI-frequency.md` — how many GFIs to support
160+
- Issue templates and labeling conventions
161+
162+
Together, these documents provide a complete view of:
163+
- GFI definition
164+
- GFI availability
165+
- GFI stewardship
166+
167+
---
168+
169+
## Summary
170+
171+
Effective GFI management is:
172+
- Supportive
173+
- Sustainable
174+
- Transparent
175+
176+
A well-managed Good First Issue benefits contributors, maintainers, and the SDK as a whole.

0 commit comments

Comments
 (0)