diff --git a/.github/ISSUE_TEMPLATE/01_good_first_issue_candidate.yml b/.github/ISSUE_TEMPLATE/01_good_first_issue_candidate.yml index 32cc9461f..574153d7a 100644 --- a/.github/ISSUE_TEMPLATE/01_good_first_issue_candidate.yml +++ b/.github/ISSUE_TEMPLATE/01_good_first_issue_candidate.yml @@ -38,30 +38,36 @@ body: value: | > [!IMPORTANT] > ### πŸ“‹ Good First Issue (GFI) Guidelines - > - > **What we generally consider good first issues:** + > A Good First Issue generally has a narrow scope and clear instructions, with examples or solution provided. + > + > Examples of acceptable GFI work include: + > + > - **Very small, explicitly defined changes to `src` functionality** + > *(rare and mechanical only β€” not behavior-changing)*, such as: + > - Adding or fixing `__str__` or `__repr__` methods **when the exact output is specified** + > - Fully specified typing fixes (e.g. adding a known return type) + > - **Refactors of existing examples** that are purely structural: + > - Splitting an existing example into functions + > - Combining a split example into a single function + > *(when explicitly instructed)* + > - **Documentation improvements** that are instruction-driven: + > - Fixing known typos or grammar issues + > - Renaming variables when new names are provided + > - Making explicitly requested changes to docstrings, comments, or print statements + > - **Functional improvements to examples** + > *(only when the additional steps are explicitly described)* + > - **Small, clearly specified edits to existing tests** + > - Adding a known assertion to an existing test file > - > - **Narrow changes or additions to `src` functionality** that use generic Python skills which can be tested by adding to an existing test. For example: - > - `__str__` functions - > - `__repr__` functions - > - Typing fixes, like return type hints or basic type conflicts - > - **Refactors of existing examples:** - > - Separating existing examples into separate functions - > - Or, conversely, taking a split example into a monolithic function - > - **Improvements to documentation** in examples and source code: - > - Docstrings: module docstrings, function docstrings - > - Inline comments - > - Addition or changes to print statements to improve clarity - > - **Functional improvements to examples:** - > - Additional steps that would help to illustrate functionality - > - **Specific additions to existing unit or integration tests** + > **What we do NOT consider Good First Issues:** > - > **What we generally do NOT consider good first issues:** + > - Writing new documentation, examples, or tests + > - Any change that requires deciding *what* to do or *how* something should behave + > - Changes to SDK behavior, public APIs, or contracts + > - Changes to DLT or protocol logic, including `to_proto` / `from_proto` + > - Work spanning multiple files, modules, or subsystems + > - Tasks requiring domain, protocol, or architectural knowledge > - > - Creation of new examples - > - Creation of new unit and integration tests - > - Changes to DLT functionality, like `to_proto` and `from_proto` - > - Anything requiring knowledge of multiple areas of the codebase > > πŸ“– *For a more detailed explanation, refer to: > [`docs/maintainers/good_first_issue_candidate_guidelines.md`](docs/maintainers/good_first_issue_candidate_guidelines.md).* @@ -72,7 +78,7 @@ body: label: πŸ‘Ύ Description of the issue description: | DESCRIBE THE ISSUE IN A WAY THAT IS UNDERSTANDABLE TO NEW CONTRIBUTORS. - YOU MUST NOT ASSUME THAT SUCH CONTRIBUTORS HAVE ANY KNOWLEDGE ABOUT THE CODEBASE OR HIERO. + YOU MUST NOT ASSUME THAT SUCH CONTRIBUTORS HAVE ANY KNOWLEDGE ABOUT THE LANGUAGE, CODEBASE OR HIERO. IT IS HELPFUL TO ADD LINKS TO THE RELEVANT DOCUMENTATION AND/OR CODE SECTIONS. BELOW IS AN EXAMPLE. value: | @@ -237,7 +243,8 @@ body: EDIT OR EXPAND THE CHECKLIST ON WHAT IS REQUIRED TO BE ABLE TO MERGE A PULL REQUEST FOR THIS ISSUE value: | To be able to merge a pull request for this issue, we need: - - [ ] **Assignment:** You must be assigned to the issue, comment: `/assign` in the issue to get assigned [see guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/training/workflow/04_assigning_issues.md) + + - [ ] **Assignment:** get assigned by commenting `/assign`[see guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/training/workflow/04_assigning_issues.md) - [ ] **Changelog Entry:** Correct changelog entry [see guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/changelog_entry.md) - [ ] **Signed commits:** commits must be DCO and GPG key signed [see guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/signing.md) - [ ] **All Tests Pass:** our workflow checks like unit and integration tests must pass @@ -254,7 +261,7 @@ body: value: | If you have never contributed to an open source project at GitHub, the following step-by-step guide will introduce you to the workflow. - - [ ] **Assignment:** You must be assigned to the issue, comment: `/assign` in the issue to get assigned [see guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/training/workflow/04_assigning_issues.md) + - [ ] **Assignment:** get assigned by commenting `/assign`[see guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/training/workflow/04_assigning_issues.md) - [ ] **Fork, Branch and Work on the issue:** Create a copy of the repository, create a branch for the issue and solve the problem. For instructions, please read our [Contributing guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/CONTRIBUTING.md) file. Further help can be found at [Set-up Training](https://github.com/hiero-ledger/hiero-sdk-python/tree/main/docs/sdk_developers/training/setup) and [Workflow Training](https://github.com/hiero-ledger/hiero-sdk-python/tree/main/docs/sdk_developers/training/workflow). - [ ] **DCO and GPG key sign each commit :** each commit must be -s and -S signed. An explanation on how to do this is at [Signing Guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/signing.md) - [ ] **Add a Changelog Entry :** your pull request will require a changelog. Read [Changelog Entry Guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/changelog_entry.md) to learn how. diff --git a/.github/ISSUE_TEMPLATE/04_good_first_issue.yml b/.github/ISSUE_TEMPLATE/04_good_first_issue.yml index 7a836e76f..fe11ef5ef 100644 --- a/.github/ISSUE_TEMPLATE/04_good_first_issue.yml +++ b/.github/ISSUE_TEMPLATE/04_good_first_issue.yml @@ -30,33 +30,39 @@ body: value: | > [!IMPORTANT] > ### πŸ“‹ Good First Issue (GFI) Guidelines - > - > **What we generally consider good first issues:** + > A Good First Issue generally has a narrow scope and clear instructions, with examples or solution provided. + > + > Examples of acceptable GFI work include: > - > - **Narrow changes or additions to `src` functionality** that use generic Python skills which can be tested by adding to an existing test. For example: - > - `__str__` functions - > - `__repr__` functions - > - Typing fixes, like return type hints or basic type conflicts - > - **Refactors of existing examples:** - > - Separating existing examples into separate functions - > - Or, conversely, taking a split example into a monolithic function - > - **Improvements to documentation** in examples and source code: - > - Docstrings: module docstrings, function docstrings - > - Inline comments - > - Addition or changes to print statements to improve clarity - > - **Functional improvements to examples:** - > - Additional steps that would help to illustrate functionality - > - **Specific additions to existing unit or integration tests** + > - **Very small, explicitly defined changes to `src` functionality** + > *(rare and mechanical only β€” not behavior-changing)*, such as: + > - Adding or fixing `__str__` or `__repr__` methods **when the exact output is specified** + > - Fully specified typing fixes (e.g. adding a known return type) + > - **Refactors of existing examples** that are purely structural: + > - Splitting an existing example into functions + > - Combining a split example into a single function + > *(when explicitly instructed)* + > - **Documentation improvements** that are instruction-driven: + > - Fixing known typos or grammar issues + > - Renaming variables when new names are provided + > - Making explicitly requested changes to docstrings, comments, or print statements + > - **Functional improvements to examples** + > *(only when the additional steps are explicitly described)* + > - **Small, clearly specified edits to existing tests** + > - Adding a known assertion to an existing test file > - > **What we generally do NOT consider good first issues:** + > **What we do NOT consider Good First Issues:** + > + > - Writing new documentation, examples, or tests + > - Any change that requires deciding *what* to do or *how* something should behave + > - Changes to SDK behavior, public APIs, or contracts + > - Changes to DLT or protocol logic, including `to_proto` / `from_proto` + > - Work spanning multiple files, modules, or subsystems + > - Tasks requiring domain, protocol, or architectural knowledge > - > - Creation of new examples - > - Creation of new unit and integration tests - > - Changes to DLT functionality, like `to_proto` and `from_proto` - > - Anything requiring knowledge of multiple areas of the codebase > > πŸ“– *For a more detailed explanation, refer to: - > [`docs/maintainers/good_first_issues_guidelines.md`](docs/maintainers/good_first_issues_guidelines.md).* + > [`docs/maintainers/good_first_issue_candidate_guidelines.md`](docs/maintainers/good_first_issue_candidate_guidelines.md).* - type: textarea id: issue @@ -64,7 +70,7 @@ body: label: πŸ‘Ύ Description of the issue description: | DESCRIBE THE ISSUE IN A WAY THAT IS UNDERSTANDABLE TO NEW CONTRIBUTORS. - YOU MUST NOT ASSUME THAT SUCH CONTRIBUTORS HAVE ANY KNOWLEDGE ABOUT THE CODEBASE OR HIERO. + YOU MUST NOT ASSUME THAT SUCH CONTRIBUTORS HAVE ANY KNOWLEDGE ABOUT THE LANGUAGE, CODEBASE OR HIERO. IT IS HELPFUL TO ADD LINKS TO THE RELEVANT DOCUMENTATION AND/OR CODE SECTIONS. BELOW IS AN EXAMPLE. value: | @@ -229,7 +235,8 @@ body: EDIT OR EXPAND THE CHECKLIST ON WHAT IS REQUIRED TO BE ABLE TO MERGE A PULL REQUEST FOR THIS ISSUE value: | To be able to merge a pull request for this issue, we need: - - [ ] **Assignment:** You must be assigned to the issue, comment: `/assign` in the issue to get assigned [see guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/training/workflow/04_assigning_issues.md) + + - [ ] **Assignment:** get assigned by commenting `/assign`[see guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/training/workflow/04_assigning_issues.md) - [ ] **Changelog Entry:** Correct changelog entry [see guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/changelog_entry.md) - [ ] **Signed commits:** commits must be DCO and GPG key signed [see guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/signing.md) - [ ] **All Tests Pass:** our workflow checks like unit and integration tests must pass @@ -246,7 +253,7 @@ body: value: | If you have never contributed to an open source project at GitHub, the following step-by-step guide will introduce you to the workflow. - - [ ] **Assignment:** You must be assigned to the issue, comment: `/assign` in the issue to get assigned [see guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/training/workflow/04_assigning_issues.md) + - [ ] **Assignment:** get assigned by commenting `/assign`[see guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/training/workflow/04_assigning_issues.md) - [ ] **Fork, Branch and Work on the issue:** Create a copy of the repository, create a branch for the issue and solve the problem. For instructions, please read our [Contributing guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/CONTRIBUTING.md) file. Further help can be found at [Set-up Training](https://github.com/hiero-ledger/hiero-sdk-python/tree/main/docs/sdk_developers/training/setup) and [Workflow Training](https://github.com/hiero-ledger/hiero-sdk-python/tree/main/docs/sdk_developers/training/workflow). - [ ] **DCO and GPG key sign each commit :** each commit must be -s and -S signed. An explanation on how to do this is at [Signing Guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/signing.md) - [ ] **Add a Changelog Entry :** your pull request will require a changelog. Read [Changelog Entry Guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/changelog_entry.md) to learn how. diff --git a/docs/GFI/GFI-Guidelines.md b/docs/GFI/GFI-Guidelines.md deleted file mode 100644 index e6a4e5758..000000000 --- a/docs/GFI/GFI-Guidelines.md +++ /dev/null @@ -1,137 +0,0 @@ -# Good First Issue (GFI) Guidelines - -## Purpose - -This document defines what qualifies as a **Good First Issue (GFI)** for SDKs in this repository. - -Good First Issues are intended to: -- Help new contributors get started successfully -- Reduce ambiguity for maintainers when labeling issues -- Provide **SDK-level clarity**, beyond organization- or project-level guidance - -While higher-level guidance exists (e.g., at the Hiero level), this document focuses specifically on **SDK expectations**. - ---- - -## What Is a Good First Issue? - -A Good First Issue should be: -- Narrow in scope -- Low risk -- Easy to test or validate -- Achievable without deep domain knowledge of the SDK - -Below are examples of changes that are generally considered good first issues. - ---- - -## Examples of Good First Issues - -### 1. Small, Focused Code Changes - -- Narrow changes or additions to existing `src` functionality -- Uses common Python skills -- Can be tested by adding to an existing test - -**Examples:** -- Adding or improving `__str__` functions -- Adding or improving `__repr__` functions -- Simple typing fixes (e.g., return type hints, resolving basic type conflicts) - ---- - -### 2. Refactoring Existing Examples - -- Separating existing examples into smaller helper functions -- Consolidating overly split examples into a single, clearer function -- Improving readability without changing behavior - ---- - -### 3. Documentation Improvements - -Documentation-only changes are excellent GFIs. - -**Examples:** -- Adding or improving module docstrings -- Adding or improving function docstrings -- Adding inline comments to clarify logic -- Improving or adding `print` statements for clarity in examples - ---- - -### 4. Improvements to Existing Examples - -- Adding small, incremental steps to examples to better demonstrate functionality -- Clarifying edge cases or expected outputs -- Improving naming or structure for educational purposes - ---- - -### 5. Test Enhancements (Limited Scope) - -- Small additions to **existing** unit or integration tests -- Improving clarity or coverage of an existing test - ---- - -## What Is *Not* a Good First Issue - -The following are **generally not considered Good First Issues**: - -- Creation of entirely new examples -- Creation of entirely new unit tests -- Creation of entirely new integration tests -- Large refactors -- Changes requiring deep architectural or domain knowledge -- Features that introduce new public APIs - -These may still be valuable contributions, but they are better suited for more experienced contributors. - ---- - -## SDK-Specific Guidelines - -Each SDK **may extend or refine** these guidelines based on its own needs. - -SDK maintainers are encouraged to: -- Add a short SDK-specific section -- Call out any exceptions or special cases -- Document SDK-specific tooling or constraints - -This approach allows: -- Consistent contributor experience across SDKs -- Easy updates without changing organization-wide guidance - ---- - -## Maintainer Responsibility - -Maintainers should: -- Label issues as `good first issue` only when they meet these guidelines -- Provide clear issue descriptions and acceptance criteria -- Include pointers to relevant files, examples, or tests when possible - -Clear labeling and descriptions significantly improve the contributor experience. - ---- - -## Updating These Guidelines - -These guidelines are expected to evolve. - -If you believe changes are needed: -- Open a discussion or pull request -- Propose SDK-specific additions rather than broad changes when possible - ---- - -## Summary - -Good First Issues should be: -- Small -- Clear -- Low-risk -- Educational - -When in doubt, favor issues that help contributors learn the SDK without overwhelming them. diff --git a/docs/GFI/GFI-Management.md b/docs/GFI/GFI-Management.md index a97e72480..82807419f 100644 --- a/docs/GFI/GFI-Management.md +++ b/docs/GFI/GFI-Management.md @@ -155,7 +155,7 @@ Updates should be treated as **process guidance**, not rigid policy. ## Relationship to Other GFI Documents This document complements: -- `GFI-guidelines.md` β€” what qualifies as a GFI +- `good_first_issues_guidelines` β€” what qualifies as a GFI (docs/maintainers/good_first_issues_guidelines.md) - `GFI-frequency.md` β€” how many GFIs to support - Issue templates and labeling conventions diff --git a/docs/maintainers/beginner-issues-guidelines.md b/docs/maintainers/beginner-issues-guidelines.md new file mode 100644 index 000000000..2df4b891a --- /dev/null +++ b/docs/maintainers/beginner-issues-guidelines.md @@ -0,0 +1,167 @@ +# Beginner Issue Guidelines + +This document defines what we **do** and **do not** consider a *Beginner Issue* in the Hiero Python SDK. + +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. + +--- + +## Table of Contents + +- [Purpose](#purpose) +- [What We Consider Beginner Issues](#what-we-consider-beginner-issues) + - [Source Changes in `src`](#source-changes-in-src) + - [Typing and Code Quality Improvements](#typing-and-code-quality-improvements) + - [Documentation Improvements](#documentation-improvements) + - [Improvements to Examples](#improvements-to-examples) + - [Test Improvements](#test-improvements) +- [What Is NOT a Beginner Issue](#what-is-not-a-beginner-issue) +- [Maintainer Guidance](#maintainer-guidance) +- [Additional Resources](#additional-resources) + +--- + +## Purpose + +The goal of a Beginner Issue is to: + +- βœ… Build confidence and independence +- βœ… Encourage light investigation +- βœ… Prepare for intermediate work + +Beginner Issues assume contributors are already familiar with: + +- Basic SDK workflow +- Basic Git +- At least beginner level programming +- Reading and navigating some of the codebase + +--- + +## What We Consider Beginner Issues + +Beginner Issues are: + +- βœ… Well-scoped +- βœ… Encourage light investigation +- βœ… Lightly challenging +- βœ… Welcome questions and discussion + +They differ from Good First Issues in that they: + +- ❗ Require **some initiative and coding experience** +- ❗ Require **working to understand existing behavior** +- ❗ Are not purely mechanical + +Here are some examples: + +### Source Changes in `src` + +#### Allowed + +- Implementing or improving `__str__` or `__repr__` methods +- Small, localized improvements to utility functions +- Minor behavior changes with clearly stated intent +- Changes that require limited understanding of how existing code behaves + +#### Not Allowed + +- Large refactors or architectural changes +- Cross-cutting changes spanning many unrelated modules + +--- + +### Typing and Code Quality Improvements + +#### Allowed + +- Adding missing type hints in simple functions +- Fixing incorrect type annotations in simple functions +- Improving type consistency in a file + +#### Not Allowed + +- Large-scale typing refactors +- Type hinting in advanced areas, like protobufs or complicated functions to interpret +- Type changes that significantly alter runtime behavior + +--- + +### Documentation Improvements + +#### Allowed + +- Writing new documentation in simple areas or narrow areas that can be researched +- Improving or expanding existing documentation or examples + +#### Not Allowed + +- Creating large documentation workflows +- Documentation changes requiring deep domain knowledge +- Documentation changes requiring high-level insights + +--- + +### Improvements to Examples + +#### Allowed + +- Creating simple examples that are similar to others +- Adding missing steps to better demonstrate functionality +- Improving ordering, clarity, or readability of examples +- Enhancing example output to be more instructive + +#### Not Allowed + +- Turning examples into production-ready implementations without significant prompting or examples + +--- + +### Test Improvements + +#### Allowed + +- Extending existing tests to cover specific additional scenarios +- Adding assertions based on observed behavior +- Improving test clarity, naming, or intent + +#### Not Allowed + +- Creating new unit or integration test suites +- Designing complex or high-level test strategies + +--- +## What is Not a Beginner Issue +### Rule of Thumb + +> If a contributor must **read code and make small decisions**, +> it’s a **Beginner Issue**. + +> If they must **interpret complex code or design systems**, +> it’s **not**. + +--- + +## Maintainer Guidance + +#### Label as a Beginner Issue if the issue: + +- βœ… Builds naturally on Good First Issues +- βœ… Requires light investigation or interpretation +- βœ… Has clear intent but not a fully scripted solution + +#### Do NOT label as a Beginner Issue if the issue: + +- ❌ Is purely mechanical (use Good First Issue instead) +- ❌ Requires protocol or DLT expertise +- ❌ Spans many unrelated parts of the codebase +- ❌ Represents architectural or design-level work + +### Additional Resources + +- [Good First Issue Guidelines](./good_first_issues_guidelines.md) +- [Contributing Guide](../../CONTRIBUTING.md) +- [DCO Signing Guide](../sdk_developers/signing.md) +- [Changelog Entry Guide](../sdk_developers/changelog_entry.md) +- [Discord Community](../discord.md) +- [Community Calls](https://zoom-lfx.platform.linuxfoundation.org/meetings/hiero?view=week) diff --git a/docs/maintainers/good_first_issue_candidate_guidelines.md b/docs/maintainers/good_first_issue_candidate_guidelines.md index d230aa647..c5975da22 100644 --- a/docs/maintainers/good_first_issue_candidate_guidelines.md +++ b/docs/maintainers/good_first_issue_candidate_guidelines.md @@ -1,199 +1,130 @@ # Good First Issue β€” Candidate Guidelines -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**. +This document defines the purpose and usage of the **`good first issue: candidate`** label, and explains when and how an issue may be promoted to a full **Good First Issue (GFI)**. + +The candidate label exists to protect the quality and trustworthiness of **Good First Issues** by ensuring issues are **fully specified, low-risk, and mechanically solvable** before being promoted. + +--- ## Table of Contents -- [Why We Use a "Candidate" Label](#-why-we-use-a-candidate-label) -- [When to Use the Candidate Label](#️-when-to-use-good-first-issue-candidate) -- [What a Candidate Is NOT](#-what-a-candidate-is-not) -- [Promoting a Candidate to GFI](#-promoting-a-candidate-to-gfi) -- [Workflow Summary](#-workflow-summary) -- [Important Considerations](#important-considerations) +- [Why We Use a Candidate Label](#why-we-use-a-candidate-label) +- [When to Use `good first issue: candidate`](#when-to-use-good-first-issue-candidate) +- [What a Candidate Is NOT](#what-a-candidate-is-not) +- [Promoting a Candidate to GFI](#promoting-a-candidate-to-gfi) --- -## 🎯 Why We Use a "Candidate" Label +## Why We Use a Candidate Label Labeling an issue as a **Good First Issue (GFI)** signals to new contributors that the issue is: -- βœ… **Well-scoped** β€” clear boundaries and deliverables -- βœ… **Low risk** β€” minimal chance of breaking changes -- βœ… **Clearly defined** β€” unambiguous requirements -- βœ… **Ready to be picked up** β€” with minimal guidance needed +- βœ… Small and well-scoped +- βœ… Low risk +- βœ… Fully specified +- βœ… Safe for first-time contributors +- βœ… Ready to be picked up without interpretation or initiative + +However, **many issues are not ready for that label immediately**. + +They might have: +- ❗ Incomplete documentation +- ❗ Uncertainty if they are in fact a good first issue -However, **not all issues start in that state**. The **`good first issue: candidate`** label exists to: | Purpose | Description | -|---------|-------------| -| 🚫 **Avoid premature labeling** | Prevent issues from being labeled as GFIs before they're ready | -| πŸ” **Allow refinement time** | Give maintainers space to clarify scope and requirements | -| πŸ“Š **Set accurate expectations** | Ensure new contributors know exactly what to do | -| πŸ“‹ **Create a clear pipeline** | Establish a workflow for curating high-quality GFIs | +|--------|-------------| +| 🚫 Avoid premature labeling | Prevent partially defined or misclassified issues from being advertised as GFIs | +| 🧭 Enforce quality standards | Ensure GFIs meet strict β€œno interpretation required” criteria | +| πŸ›  Allow refinement time | Give maintainers space to fully specify scope and solution | +| πŸ“‹ Create a clear pipeline | Establish a safe promotion path to GFI | -This approach helps us prioritize **quality over quantity** when advertising beginner-friendly work. +The candidate label is **not a softer GFI** β€” it is a **holding state**. --- -## 🏷️ When to Use `good first issue: candidate` +## When to Use `good first issue: candidate` -Apply the **candidate** label when an issue: +Apply the **candidate** label when you believe the issue is a good first issue, not documented enough, or have some doubt with its difficulty: -### βœ… Fits the General Criteria +### βœ… Appears Potentially Suitable as a GFI -- *Might* be suitable as a GFI based on initial assessment -- Fits within the [allowed categories](./good_first_issues_guidelines.md#allowed-categories) of GFI work -- Appears to be small in scope and low risk +- The change is *likely* small, localized, and low risk +- The issue fits within the **allowed GFI categories** (docs, examples, typing, small mechanical edits) +- The issue is *not* exploratory and does *not* require design decisions -### ⏳ Still Needs Work +Suitability can be assessed [here](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/maintainers/good_first_issues_guidelines.md) -- **Needs clarification** β€” requirements are ambiguous or incomplete -- **Needs refinement** β€” scope could be narrowed or better defined -- **Needs confirmation** β€” maintainer review required to verify suitability -- **Needs acceptance criteria** β€” clear success conditions not yet defined +### βœ… Requires Some Refinement -### πŸ“ Example Scenarios +One or more of the following is still missing: -| Scenario | Why Use Candidate? | -|----------|-------------------| -| User reports a documentation gap | Needs scoping to determine exact changes required | -| Bug in example code identified | Need to confirm it's isolated and straightforward to fix | -| Type annotation improvement suggested | Need to verify it doesn't affect runtime behavior | -| Test assertion missing | Need to confirm it extends existing tests only | +- ❗ Explicit step-by-step instructions +- ❗ Clearly defined acceptance criteria ---- - -## 🚦 What a Candidate Is NOT +### βœ… Difficulty is Uncertain -The **candidate** label should **NOT** be used for: +Use the `good first issue: candidate` label when you believe it is a Good First Issue but are not sure -### ❌ Large or Cross-Cutting Changes +- βœ… Requires maintainer approval -Issues that span multiple modules, packages, or require architectural understanding. +Check by reading good first issue guidelines [here](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/maintainers/good_first_issues_guidelines.md) -### ❌ Core Protocol or SDK Logic +If easy issues are not 'Good First Issues' are in fact 'beginner' issues. -Changes to: -- `to_proto` / `from_proto` methods -- Serialization/deserialization logic -- Network or wire-level behavior +## What a Candidate Is NOT -### ❌ Exploratory or Investigative Work +The **candidate** label must **NOT** be used for issues that clearly do not qualify as GFIs. -Issues where the solution path is unclear or requires research. +### ❌ Not for Issues Requiring Decisions -### ❌ Blocked Issues +If a contributor must decide: +- *what* to change +- *how* something should behave +- *what* is correct or expected -Issues that depend on external decisions, other PRs, or upstream changes. +β†’ the issue is **not** a candidate. ---- +### ❌ Not for Core or Behavioral Changes -> ⚠️ **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. - ---- +Do **not** use the candidate label for changes involving: -## ✨ Promoting a Candidate to GFI +- SDK or protocol behavior +- Public APIs or contracts +- `to_proto` / `from_proto` logic +- Serialization, deserialization, or networking -A candidate should be promoted to a full **Good First Issue** when: +### ❌ Not for Exploratory or Blocked Work -### Readiness Checklist +- Investigations or debugging tasks +- Issues dependent on other PRs or decisions +- Work requiring domain or protocol knowledge -- [ ] **Clear description** β€” the problem and solution are well-defined -- [ ] **Scoped appropriately** β€” changes are localized and low-risk -- [ ] **Acceptance criteria defined** β€” clear conditions for success -- [ ] **Documentation linked** β€” relevant guides are referenced -- [ ] **No blockers** β€” no dependencies on other work -- [ ] **Maintainer approved** β€” a maintainer has reviewed and confirmed suitability - -### Promotion Process - -1. **Review the candidate issue** against [GFI guidelines](./good_first_issues_guidelines.md) -2. **Add missing details** β€” clarify requirements, add acceptance criteria -3. **Remove `good first issue: candidate`** label -4. **Add `Good First Issue`** label -5. **Optionally notify** in comments that the issue is ready for contributors - ---- - -## πŸ“Š Workflow Summary - -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ Issue Created β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β–Ό -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ Initial Assessment by Maintainer β”‚ -β”‚ β”‚ -β”‚ Is this potentially a Good First Issue? β”‚ -β”‚ β”‚ -β”‚ β€’ Small scope? β”‚ -β”‚ β€’ Low risk? β”‚ -β”‚ β€’ Fits allowed categories? β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ β”‚ β”‚ - β–Ό β–Ό β–Ό - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ No β”‚ β”‚ Maybe β”‚ β”‚ Yes β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ β”‚ β”‚ - β–Ό β–Ό β–Ό - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ Label normally β”‚ β”‚ Label as β”‚ β”‚ Label as β”‚ - β”‚ (not GFI) β”‚ β”‚ `candidate` β”‚ β”‚ Good First β”‚ - β”‚ β”‚ β”‚ β”‚ β”‚ Issue β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β–Ό - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ Refine & Review β”‚ - β”‚ β”‚ - β”‚ β€’ Add details β”‚ - β”‚ β€’ Define scope β”‚ - β”‚ β€’ Set criteria β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β–Ό - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ Promote to GFI β”‚ - β”‚ when ready β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` +> ⚠️ If an issue clearly does *not* meet GFI criteria, **do not label it as a candidate**. +> The candidate label is for issues that *might* qualify after refinement β€” not for issues that never will. --- -## Important Considerations +## Promoting a Candidate to GFI -### Why This Matters +A candidate may be promoted to a full **Good First Issue** only when **all** of the following are true. -1. **Good First Issues are automatically promoted** by GitHub and Hiero, making them highly visible to potential contributors worldwide +### βœ… Readiness Checklist -2. **New contributors trust the GFI label** β€” they expect issues to be ready and achievable +- [ ] The problem is clearly described +- [ ] The solution is **explicitly specified** +- [ ] The change is small, localized, and low risk +- [ ] The issue touches a single file or clearly defined location +- [ ] Acceptance criteria are defined and objective +- [ ] No interpretation or initiative is required -3. **Poorly scoped GFIs waste contributor time** β€” and can discourage future contributions +### πŸ” Promotion Process -4. **Quality GFIs build community** β€” successful first contributions lead to long-term contributors - -### Best Practices - -| Do | Don't | -|----|-------| -| βœ… Use candidate for uncertain issues | ❌ Rush issues to GFI status | -| βœ… Take time to refine candidates | ❌ Label obviously unsuitable issues as candidates | -| βœ… Add clear acceptance criteria before promotion | ❌ Promote candidates without review | -| βœ… Link to relevant documentation | ❌ Assume contributors know the codebase | - ---- +1. Review the issue against the **Good First Issue Guidelines** [here](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/maintainers/good_first_issues_guidelines.md) +2. Add missing details, steps, and acceptance criteria +3. Remove the `good first issue: candidate` label +4. Add the **Good First Issue** label -## Additional Resources -- [Good First Issue Guidelines](./good_first_issues_guidelines.md) β€” what qualifies as a GFI -- [Contributing Guide](../../CONTRIBUTING.md) β€” how to contribute -- [DCO Signing Guide](../sdk_developers/signing.md) β€” commit signing requirements -- [Discord Community](../discord.md) β€” get help from the community -- [Community Calls](https://zoom-lfx.platform.linuxfoundation.org/meetings/hiero?view=week) β€” weekly office hours diff --git a/docs/maintainers/good_first_issues_guidelines.md b/docs/maintainers/good_first_issues_guidelines.md index 7e744ae79..e5102f8cc 100644 --- a/docs/maintainers/good_first_issues_guidelines.md +++ b/docs/maintainers/good_first_issues_guidelines.md @@ -5,16 +5,18 @@ This document defines what we **do** and **do not** consider a *Good First Issue ## Table of Contents - [Purpose](#purpose) -- [Allowed Categories](#allowed-categories) - - [Small, Focused Source Changes](#-small-focused-source-changes) - - [Typing Improvements](#-typing-improvements) - - [Refactors of Existing Examples](#-refactors-of-existing-examples) - - [Documentation Improvements](#-documentation-improvements) - - [Print and Output Clarity](#️-print-and-output-clarity-examples-only) - - [Functional Improvements to Examples](#️-functional-improvements-to-examples) - - [Test Improvements](#-test-improvements-additive-only) -- [What We Do NOT Consider Good First Issues](#-what-we-do-not-consider-good-first-issues) +- [What We Consider Good First Issues](#what-we-consider-good-first-issues) + - [Small, Focused Source Changes](#small-focused-source-changes) + - [Typing Improvements](#typing-improvements) + - [Refactors of Existing Examples](#refactors-of-existing-examples) + - [Documentation Improvements](#documentation-improvements) + - [Print and Output Clarity](#print-and-output-clarity-examples-only) + - [Functional Improvements to Examples](#functional-improvements-to-examples) + - [Test Improvements](#test-improvements) +- [What Is NOT a Good First Issue](#-summary-what-is-not-a-good-first-issue) - [Maintainer Guidance](#-maintainer-guidance) +- [Additional Resources](#additional-resources) + --- @@ -22,199 +24,119 @@ This document defines what we **do** and **do not** consider a *Good First Issue The goal of a Good First Issue is to: -- **Help new contributors get onboarded successfully** β€” providing a clear, achievable starting point -- **Build confidence with a meaningful but low-risk contribution** β€” ensuring success without overwhelming complexity -- **Reduce maintainer overhead during first-time contributions** β€” making review and guidance straightforward +- βœ… **Help new contributors get onboarded successfully** by providing a clear, achievable starting point. + +Good First Issues are often a contributor’s **first interaction with open source** and are intended to help them learn our workflow with confidence. + + +## What We Consider Good First Issues -These issues are intentionally: +Good First Issues are intentionally: - βœ… Small - βœ… Low risk - βœ… Easy to review - βœ… Safe for first-time contributors ---- - -## Allowed Categories - -### 🧡 Small, Focused Source Changes +Importantly, they have: -Limited, localized changes to existing source files that do not alter public behavior or SDK contracts. +- βœ… A **very clear, explicitly described, or provided solution** +- βœ… **No requirement to interpret code behavior or make design decisions** -#### Allowed - -- Adding or improving simple string helper functions -- Implementing or improving `__str__` or `__repr__` methods -- Fixing or clarifying edge cases in existing utility functions - -#### Examples - -- Improve formatting of a `__repr__` output -- Make a string helper more robust or readable -- Clarify handling of empty or `None` inputs in a utility function +Below are examples that we consider good first issues: --- +### Small, Focused Source Changes -### 🧩 Typing Improvements +> ⚠️ **Note:** In most cases, changes to `src` functionality are **not** Good First Issues. +> This category applies only when the change is **purely mechanical and fully specified**. -Improvements to type annotations that increase correctness or clarity without changing runtime behavior. +#### Allowed (rare, explicit cases only) -#### Allowed - -- Adding missing return type hints -- Fixing incorrect or overly broad type annotations -- Resolving basic type conflicts flagged by type checkers +- Very small, explicitly described edits to existing code +- Changes that do **not** require understanding how the code is used elsewhere -#### Examples +#### Not Allowed -- Change `-> Any` to a more specific return type -- Fix mismatched return types in conditional branches -- Tighten a `Dict[str, Any]` to a more precise type +- Any change that requires deciding *how* something should behave +- Any change that affects public behavior or SDK contracts --- -### πŸ”„ Refactors of Existing Examples +### Typing Improvements -Refactors that improve clarity, structure, or readability of **existing examples only**. +Typing changes must be **fully specified** and **mechanical**. #### Allowed -- Refactoring an example for clarity or readability -- Extracting repeated logic into helper functions -- Renaming variables to be more descriptive - -#### Allowed Directions +- Adding missing return type hints **when the expected type is explicitly stated** +- Fixing incorrect or overly broad type annotations **when the correct type is provided** -- Split a large example into smaller, named functions -- Combine a split example back into a single monolithic function for simplicity +#### Not Allowed -> ⚠️ **Note:** This category applies **only** to existing examples. -> Creating new examples is **out of scope** for GFIs. +- Inferring correct types by interpreting code +- Large or cross-file typing refactors +- Resolving complex type-system issues --- -### πŸ“š Documentation Improvements +### Documentation Improvements -Improvements to documentation that clarify intent or behavior without changing functionality. - -#### Includes - -- Module-level docstrings -- Function and method docstrings -- Inline comments that explain *why* (not what) code does something - -#### Examples - -- Clarify a confusing or outdated docstring -- Add explanation for non-obvious behavior -- Improve wording or structure for readability - ---- - -### πŸ–¨οΈ Print and Output Clarity (Examples Only) - -Improvements to output clarity in example code. +Documentation tasks must be **explicitly scoped** and **instruction-driven**. #### Allowed -- Improving clarity of `print()` statements -- Making output more descriptive or user-friendly -- Standardizing message formatting (prefixes, spacing, context) +- Remaing variable names when new names are provided +- Fixing identified typos or grammar issues +- Making explicitly provided changes to docstrings, comments or print statements +- Splitting a large example into smaller functions +- Combining a split example into a single function -#### Examples +#### Not Allowed -- Replace ambiguous prints like `"Done"` with meaningful context -- Add explanatory text before printing values -- Make output ordering easier to follow +- Writing new documentation +- Adding docstrings or comments that require interpreting code behavior +- Deciding *what* should be documented or printed +- Deciding which steps should exist --- -### βš™οΈ Functional Improvements to Examples - -Small functional improvements that better illustrate **existing behavior** in examples. - -#### Allowed - -- Adding missing steps that improve understanding -- Improving ordering or structure of example code -- Clarifying error-handling paths +### Test Improvements -#### Examples +> ⚠️ Most test-related work belongs in **Beginner or Intermediate Issues**. -- Add an explicit setup step that was previously implied -- Improve error-handling clarity in an example -- Make control flow easier to follow +#### Allowed (rare, explicit cases only) ---- +- Adding a clearly specified assertion to an existing test +- Small mechanical edits with no test-design decisions -### πŸ§ͺ Test Improvements (Additive Only) - -Small, additive improvements to **existing** tests. - -#### Allowed - -- Adding specific assertions to existing tests -- Extending tests to cover an obvious edge case -- Improving test names or failure messages - -#### Examples - -- Add an assertion for a previously untested branch -- Improve test failure messages for clarity - -> ⚠️ Tests must extend **existing test files**. -> Creating new test suites or frameworks is **out of scope**. - ---- - -## 🚫 What We Do NOT Consider Good First Issues - -The following types of changes are **explicitly out of scope** for GFIs. - ---- - -### ❌ New Examples - -- Creating entirely new examples -- Adding new example files or workflows - -These require deeper understanding of intended usage patterns. - ---- - -### ❌ New Unit or Integration Tests +#### Not Allowed - Creating new test files -- Designing new test strategies or frameworks - -Test creation often requires broader architectural context. +- Designing new test cases +- Extending coverage based on interpretation --- -### ❌ Core DLT or Protocol Logic +## 🚫 Summary: What Is NOT a Good First Issue -- Changes to `to_proto` / `from_proto` -- Modifying serialization or deserialization logic -- Any change affecting network or wire-level behavior - -These areas are sensitive and require domain expertise. +- ❌ Issues without a clearly defined or provided solution +- ❌ Tasks requiring interpretation, investigation, or initiative +- ❌ Changes to `src` functionality that affect behavior +- ❌ Creating new examples, tests, or documentation +- ❌ Work spanning multiple files or subsystems --- -### ❌ Cross-Cutting or Architectural Changes - -- Refactors spanning multiple modules or packages -- Changes requiring understanding of multiple subsystems -- Performance optimizations or concurrency changes +### Rule of Thumb -These are better suited for experienced contributors. +> If a contributor must **decide what to do**, +> it is **not** a Good First Issue. --- ## πŸ“Œ Maintainer Guidance -When evaluating whether to label an issue as a Good First Issue, consider: - ### Label as GFI if the issue: - βœ… Touches a **single file or module** @@ -222,6 +144,7 @@ When evaluating whether to label an issue as a Good First Issue, consider: - βœ… Requires **no domain or protocol knowledge** - βœ… Can be **reviewed quickly** - βœ… Has **low risk of breaking changes** +- βœ… Has a **clear step-by-step solution** ### Do NOT label as GFI if the issue: @@ -230,13 +153,19 @@ When evaluating whether to label an issue as a Good First Issue, consider: - ❌ Requires **domain or protocol knowledge** - ❌ Could have **unintended side effects** - ❌ Needs **extensive review or testing** +- ❌ Requires initiative or interpretation to solve + +Instead, these are better suited as **Beginner Issues**. + +--- ### Important Reminders -1. **Good First Issues are promoted automatically** by GitHub and Hiero, making them highly visible to new contributors -2. **Quality over quantity** β€” we prefer fewer, clearly safe GFIs over many ambiguous ones -3. **Clear acceptance criteria** β€” every GFI should have well-defined success conditions -4. **Link to documentation** β€” include relevant guides to help contributors succeed +1. **Good First Issues are promoted automatically** by GitHub and Hiero, making them highly visible +2. **Good First Issues are self-assigned** (via `/assign`), so they must be achievable by anyone +3. **Quality over quantity** β€” prefer fewer, clearly safe GFIs +4. **Clear acceptance criteria** β€” every GFI should define what β€œdone” means +5. **Link to documentation** β€” include relevant guides to help contributors succeed ---