docs: add GFI-Guidelines Doc File

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.

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.