Skip to content

Commit f6fd6af

Browse files
exploreriiiexploreriii
authored
docs: advanced issue guidelines (#1331)
Signed-off-by: exploreriii <[email protected]>
1 parent dd922b6 commit f6fd6af

File tree

2 files changed

+209
-0
lines changed

2 files changed

+209
-0
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
6868
- Add a workflow to notify the team when issues are labeled as “good first issues” or identified as candidates for that label: `bot-gfi-notify-team.yml`(#1115)
6969
- Added **str** and **repr** to AccountBalance
7070
- Added GitHub workflow that makes sure newly added test files follow pytest test files naming conventions (#1054)
71+
- Added advanced issue template
7172
- Added advanced issue template for contributors `.github/ISSUE_TEMPLATE/06_advanced_issue.yml`.
7273
- Add new tests to `tests/unit/topic_info_query_test.py` (#1124)
7374
- Added `coding_token_transactions.md` for a high level overview training on how token transactions are created in the python sdk.

‎docs/maintainers/advanced-issue-guidelines.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# Advanced Issue Guidelines
2+
3+
This document defines what we **do** and **do not** consider an *Advanced Issue*.
4+
5+
Advanced Issues represent the **highest tier of contributor work** and are intended for contributors with deep familiarity with the codebase, strong architectural judgment, and the ability to own complex changes end-to-end.
6+
7+
Advanced contributors are trusted to make **high-impact decisions** that may affect core behavior, public APIs, or long-term maintainability of the SDK.
8+
9+
---
10+
11+
## Table of Contents
12+
13+
- [Purpose](#purpose)
14+
- [What We Consider Advanced Issues](#what-we-consider-advanced-issues)
15+
- [Source Changes in `src`](#source-changes-in-src)
16+
- [Architecture, Design, and Refactors](#architecture-design-and-refactors)
17+
- [Typing, Interfaces, and Contracts](#typing-interfaces-and-contracts)
18+
- [Documentation and Developer Guidance](#documentation-and-developer-guidance)
19+
- [Examples and Public UX](#examples-and-public-ux)
20+
- [Testing and Validation](#testing-and-validation)
21+
- [What Is NOT an Advanced Issue](#what-is-not-an-advanced-issue)
22+
- [Maintainer Guidance](#maintainer-guidance)
23+
- [Additional Resources](#additional-resources)
24+
25+
---
26+
27+
## Purpose
28+
29+
The goal of an Advanced Issue is to:
30+
31+
- ✅ Enable **high-impact, high-responsibility contributions**
32+
- ✅ Improve core correctness, extensibility, or maintainability
33+
- ✅ Introduce or evolve architectural patterns
34+
- ✅ Prepare contributors for long-term ownership and stewardship
35+
36+
Advanced Issues assume contributors are already comfortable with:
37+
38+
- The full SDK development workflow
39+
- Navigating and reasoning across many modules
40+
- Understanding implicit invariants and contracts
41+
- Evaluating backwards compatibility and migration risk
42+
43+
Contributors are expected to:
44+
45+
- Proactively identify risks and edge cases
46+
- Propose and justify design decisions
47+
- Communicate trade-offs clearly
48+
- Take responsibility for downstream impact
49+
50+
---
51+
52+
## What We Consider Advanced Issues
53+
54+
Advanced Issues are:
55+
56+
- ✅ Clearly motivated but **not fully specified**
57+
- ✅ Often span **multiple subsystems or layers**
58+
- ✅ Require architectural reasoning and design judgment
59+
- ✅ May involve **behavior changes or API evolution**
60+
- ✅ High impact, with **medium to high risk if done incorrectly**
61+
62+
They differ from **Intermediate Issues** in that they:
63+
64+
- ❗ Require **deep conceptual understanding**
65+
- ❗ Require **design ownership**, not just implementation
66+
- ❗ May require proposing new abstractions or patterns
67+
- ❗ May affect long-term API or architectural direction
68+
69+
---
70+
71+
### Source Changes in `src`
72+
73+
#### Allowed
74+
75+
- Significant behavior changes with explicit rationale
76+
- Refactors spanning multiple related subsystems
77+
- Changes to core execution paths or abstractions
78+
- Bug fixes that require deep investigation across layers
79+
- Improvements that trade short-term complexity for long-term clarity
80+
81+
#### Not Allowed
82+
83+
- Trivial or mechanical changes (use lower-tier labels)
84+
- Changes without a clear problem statement or motivation
85+
86+
---
87+
88+
### Architecture, Design, and Refactors
89+
90+
#### Allowed
91+
92+
- Introducing new abstractions or subsystems
93+
- Reworking existing designs to address systemic issues
94+
- Decoupling tightly coupled components
95+
- Improving extensibility or testability through redesign
96+
97+
#### Not Allowed
98+
99+
- Architectural churn without demonstrated benefit
100+
- Refactors without migration or compatibility consideration
101+
102+
---
103+
104+
### Typing, Interfaces, and Contracts
105+
106+
#### Allowed
107+
108+
- Changes to public or internal interfaces with justification
109+
- Refining or formalizing implicit contracts
110+
- Improving type precision across large areas of the codebase
111+
- Introducing new shared types or protocols
112+
113+
#### Not Allowed
114+
115+
- Interface changes without documented impact
116+
- Type-system experimentation without clear benefit
117+
118+
---
119+
120+
### Documentation and Developer Guidance
121+
122+
#### Allowed
123+
124+
- Writing or revising architectural documentation
125+
- Explaining non-obvious design decisions
126+
- Updating guides to reflect behavioral or API changes
127+
- Adding migration notes or deprecation guidance
128+
129+
#### Not Allowed
130+
131+
- Documentation changes disconnected from code changes
132+
- High-level conceptual docs without implementation context
133+
134+
---
135+
136+
### Examples and Public UX
137+
138+
#### Allowed
139+
140+
- Designing new examples for advanced or complex features
141+
- Updating examples to reflect new APIs or workflows
142+
- Improving clarity around advanced usage patterns
143+
144+
#### Not Allowed
145+
146+
- Example changes without corresponding documentation
147+
- Large example suites without instructional purpose
148+
149+
---
150+
151+
### Testing and Validation
152+
153+
#### Allowed
154+
155+
- Designing new test strategies or patterns
156+
- Adding comprehensive coverage for new abstractions
157+
- Refactoring test architecture to support new designs
158+
- Introducing regression tests for complex scenarios
159+
160+
#### Not Allowed
161+
162+
- Skipping tests for high-impact changes
163+
- Relying solely on existing coverage for new behavior
164+
165+
---
166+
167+
## What Is NOT an Advanced Issue
168+
169+
### Rule of Thumb
170+
171+
> If a contributor must **design systems, evaluate trade-offs,
172+
> and take responsibility for long-term impact**,
173+
> it’s an **Advanced Issue**.
174+
175+
> If the work can be safely completed by following existing patterns
176+
> without design ownership,
177+
> it’s **not**.
178+
179+
---
180+
181+
## Maintainer Guidance
182+
183+
### Label as an Advanced Issue if the issue:
184+
185+
- ✅ Requires architectural or design decisions
186+
- ✅ Has multiple valid solution paths
187+
- ✅ May affect public APIs or core behavior
188+
- ✅ Requires careful backwards-compatibility reasoning
189+
- ✅ Is suitable for experienced, trusted contributors
190+
191+
### Do NOT label as an Advanced Issue if the issue:
192+
193+
- ❌ Is purely mechanical or scripted
194+
- ❌ Is well-bounded with minimal risk (use Intermediate)
195+
- ❌ Is exploratory without clear goals
196+
- ❌ Requires organizational or product-level decisions
197+
198+
---
199+
200+
## Additional Resources
201+
202+
- [Intermediate Issue Guidelines](./intermediate_issue_guidelines.md)
203+
- [Contributing Guide](../../CONTRIBUTING.md)
204+
- [SDK Developer Docs](../sdk_developers)
205+
- [DCO Signing Guide](../sdk_developers/signing.md)
206+
- [Changelog Entry Guide](../sdk_developers/changelog_entry.md)
207+
- [Discord Community](../discord.md)
208+
- [Community Calls](https://zoom-lfx.platform.linuxfoundation.org/meetings/hiero?view=week)

0 commit comments

Comments
 (0)