Skip to content

Commit 442652b

Browse files
exploreriiiexploreriii
committed
feat: beginner issue guidelines
Signed-off-by: exploreriii <133720349+exploreriii@users.noreply.github.com>
1 parent ce409ca commit 442652b

1 file changed

Lines changed: 167 additions & 0 deletions

File tree

‎docs/maintainers/beginner-issues-guidelines.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Beginner Issue Guidelines
2+
3+
This document defines what we **do** and **do not** consider a *Beginner Issue* in the Hiero Python SDK.
4+
5+
Beginner Issues represent the **next step after Good First Issues** and are intended for contributors who are ready to take on slightly more responsibility and decision-making.
6+
7+
---
8+
9+
## Table of Contents
10+
11+
- [Purpose](#purpose)
12+
- [What We Consider Beginner Issues](#what-we-consider-beginner-issues)
13+
- [Source Changes in `src`](#source-changes-in-src)
14+
- [Typing and Code Quality Improvements](#typing-and-code-quality-improvements)
15+
- [Documentation Improvements](#documentation-improvements)
16+
- [Improvements to Examples](#improvements-to-examples)
17+
- [Test Improvements](#test-improvements)
18+
- [What Is NOT a Beginner Issue](#what-is-not-a-beginner-issue)
19+
- [Maintainer Guidance](#maintainer-guidance)
20+
- [Additional Resources](#additional-resources)
21+
22+
---
23+
24+
## Purpose
25+
26+
The goal of a Beginner Issue is to:
27+
28+
- ✅ Build confidence and independence
29+
- ✅ Encourage light investigation
30+
- ✅ Prepare for intermediate work
31+
32+
Beginner Issues assume contributors are already familiar with:
33+
34+
- Basic SDK workflow
35+
- Basic Git
36+
- At least beginner level programming
37+
- Reading and navigating some of the codebase
38+
39+
---
40+
41+
## What We Consider Beginner Issues
42+
43+
Beginner Issues are:
44+
45+
- ✅ Well-scoped
46+
- ✅ Encourage light investigation
47+
- ✅ Lightly challenging
48+
- ✅ Welcome questions and discussion
49+
50+
They differ from Good First Issues in that they:
51+
52+
- ❗ Require **some initiative and coding experience**
53+
- ❗ Require **working to understand existing behavior**
54+
- ❗ Are not purely mechanical
55+
56+
Here are some examples:
57+
58+
### Source Changes in `src`
59+
60+
#### Allowed
61+
62+
- Implementing or improving `__str__` or `__repr__` methods
63+
- Small, localized improvements to utility functions
64+
- Minor behavior changes with clearly stated intent
65+
- Changes that require limited understanding of how existing code behaves
66+
67+
#### Not Allowed
68+
69+
- Large refactors or architectural changes
70+
- Cross-cutting changes spanning many unrelated modules
71+
72+
---
73+
74+
### Typing and Code Quality Improvements
75+
76+
#### Allowed
77+
78+
- Adding missing type hints in simple functions
79+
- Fixing incorrect type annotations in simple functions
80+
- Improving type consistency in a file
81+
82+
#### Not Allowed
83+
84+
- Large-scale typing refactors
85+
- Type hinting in advanced areas, like protobufs or complicated functions to interpret
86+
- Type changes that significantly alter runtime behavior
87+
88+
---
89+
90+
### Documentation Improvements
91+
92+
#### Allowed
93+
94+
- Writing new documentation in simple areas or narrow areas that can be researched
95+
- Improving or expanding existing documentation or examples
96+
97+
#### Not Allowed
98+
99+
- Creating large documentation workflows
100+
- Documentation changes requiring deep domain knowledge
101+
- Documentation changes requiring high-level insights
102+
103+
---
104+
105+
### Improvements to Examples
106+
107+
#### Allowed
108+
109+
- Creating simple examples that are similar to others
110+
- Adding missing steps to better demonstrate functionality
111+
- Improving ordering, clarity, or readability of examples
112+
- Enhancing example output to be more instructive
113+
114+
#### Not Allowed
115+
116+
- Turning examples into production-ready implementations without significant prompting or examples
117+
118+
---
119+
120+
### Test Improvements
121+
122+
#### Allowed
123+
124+
- Extending existing tests to cover specific additional scenarios
125+
- Adding assertions based on observed behavior
126+
- Improving test clarity, naming, or intent
127+
128+
#### Not Allowed
129+
130+
- Creating new unit or integration test suites
131+
- Designing complex or high-level test strategies
132+
133+
---
134+
## What is Not a Beginner Issue
135+
### Rule of Thumb
136+
137+
> If a contributor must **read code and make small decisions**,
138+
> it’s a **Beginner Issue**.
139+
140+
> If they must **interpret complex code or design systems**,
141+
> it’s **not**.
142+
143+
---
144+
145+
## Maintainer Guidance
146+
147+
#### Label as a Beginner Issue if the issue:
148+
149+
- ✅ Builds naturally on Good First Issues
150+
- ✅ Requires light investigation or interpretation
151+
- ✅ Has clear intent but not a fully scripted solution
152+
153+
#### Do NOT label as a Beginner Issue if the issue:
154+
155+
- ❌ Is purely mechanical (use Good First Issue instead)
156+
- ❌ Requires protocol or DLT expertise
157+
- ❌ Spans many unrelated parts of the codebase
158+
- ❌ Represents architectural or design-level work
159+
160+
### Additional Resources
161+
162+
- [Good First Issue Guidelines](./good_first_issues_guidelines.md)
163+
- [Contributing Guide](../../CONTRIBUTING.md)
164+
- [DCO Signing Guide](../sdk_developers/signing.md)
165+
- [Changelog Entry Guide](../sdk_developers/changelog_entry.md)
166+
- [Discord Community](../discord.md)
167+
- [Community Calls](https://zoom-lfx.platform.linuxfoundation.org/meetings/hiero?view=week)

0 commit comments

Comments
 (0)