diff --git a/CHANGELOG.md b/CHANGELOG.md index b73d51298..404b60e14 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1. ### Added +- Added SDK-level Good First Issue (GFI) guidelines for maintainers to clarify what qualifies as a good first issue. - Codecov workflow - Added unit tests for `key_format.py` to improve coverage. - Fix inactivity bot execution for local dry-run testing. diff --git a/docs/GFI/GFI-Guidelines.md b/docs/GFI/GFI-Guidelines.md new file mode 100644 index 000000000..e6a4e5758 --- /dev/null +++ b/docs/GFI/GFI-Guidelines.md @@ -0,0 +1,137 @@ +# 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.