diff --git a/CHANGELOG.md b/CHANGELOG.md index 404b60e14..222f18aa2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,19 +6,19 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1. ## [Unreleased] - - ### 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. +- Added comprehensive Good First Issue guidelines documentation (`docs/maintainers/good_first_issue_candidate_guidelines.md`) (#1070) - Added documentation: "Testing GitHub Actions using Forks" (`docs/sdk_developers/training/testing_forks.md`). - Unified the inactivity-unassign bot into a single script with `DRY_RUN` support, and fixed handling of cross-repo PR references for stale detection. - Added unit tests for `SubscriptionHandle` class covering cancellation state, thread management, and join operations. - Refactored `account_create_transaction_create_with_alias.py` example by splitting monolithic function into modular functions: `generate_main_and_alias_keys()`, `create_account_with_ecdsa_alias()`, `fetch_account_info()`, `print_account_summary()` (#1016) - Added `.github/workflows/bot-pr-auto-draft-on-changes.yml` to automatically convert PRs to draft and notify authors when reviewers request changes. -- +- - Modularized `transfer_transaction_fungible` example by introducing `account_balance_query()` & `transfer_transaction()`.Renamed `transfer_tokens()` → `main()` - Phase 2 of the inactivity-unassign bot: Automatically detects stale open pull requests (no commit activity for 21+ days), comments with a helpful InactivityBot message, closes the stale PR, and unassigns the contributor from the linked issue. - Added `__str__()` to CustomFixedFee and updated examples and tests accordingly. @@ -37,7 +37,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1. - Support selecting specific node account ID(s) for queries and transactions and added `Network._get_node()` with updated execution flow (#362) - Add TLS support with two-stage control (`set_transport_security()` and `set_verify_certificates()`) for encrypted connections to Hedera networks. TLS is enabled by default for hosted networks (mainnet, testnet, previewnet) and disabled for local networks (solo, localhost) (#855) - Add PR inactivity reminder bot for stale pull requests `.github/workflows/pr-inactivity-reminder-bot.yml` -- Add comprehensive training documentation for _Executable class `docs/sdk_developers/training/executable.md` +- Add comprehensive training documentation for \_Executable class `docs/sdk_developers/training/executable.md` - Added empty `docs/maintainers/good_first_issues.md` file for maintainers to write Good First Issue guidelines (#1034) - Added new `.github/ISSUE_TEMPLATE/04_good_first_issue_candidate.yml` file (1068)(https://github.com/hiero-ledger/hiero-sdk-python/issues/1068) - Enhanced `.github/ISSUE_TEMPLATE/01_good_first_issue.yml` with welcoming message and acceptance criteria sections to guide contributors in creating quality GFIs (#1052) @@ -45,6 +45,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1. - Added Issue Reminder (no-PR) bot, .github/scripts/issue_reminder_no_pr.sh and .github/workflows/bot-issue-reminder-no-pr.yml to automatically detect assigned issues with no linked pull requests for 7+ days and post a gentle ReminderBot comment.(#951) ### Changed + - Improved consistency of transaction examples (#1120) - Refactored `account_create_transaction_with_fallback_alias.py` by splitting the monolithic `create_account_with_fallback_alias` function into modular functions: `generate_fallback_key`, `fetch_account_info`, and `print_account_summary`. The existing `setup_client()` function was reused for improved readability and structure (#1018) - Allow `PublicKey` for `TokenUpdateKeys` in `TokenUpdateTransaction`, enabling non-custodial workflows where operators can build transactions using only public keys (#934). @@ -60,10 +61,9 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1. - Cleaned up `token_airdrop_claim_auto` example for pylint compliance (no functional changes). (#1079) - Formatted `examples/query` using black (#1082)(https://github.com/hiero-ledger/hiero-sdk-python/issues/1082) - Update team notification script and workflow for P0 issues 'p0_issues_notify_team.js' -- Rename test files across the repository to ensure they consistently end with _test.py (#1055) +- Rename test files across the repository to ensure they consistently end with \_test.py (#1055) - Cleaned up `token_airdrop_claim_signature_required` example for pylint compliance (no functional changes). (#1080) - ### Fixed - Fix token association verification in `token_airdrop_transaction.py` to correctly check if tokens are associated by using `token_id in token_balances` instead of incorrectly displaying zero balances which was misleading (#[815]) @@ -638,4 +638,3 @@ contract_call_local_pb2.ContractLoginfo -> contract_types_pb2.ContractLoginfo ### Removed - N/A - diff --git a/docs/maintainers/good_first_issue_candidate_guidelines.md b/docs/maintainers/good_first_issue_candidate_guidelines.md new file mode 100644 index 000000000..59bb67353 --- /dev/null +++ b/docs/maintainers/good_first_issue_candidate_guidelines.md @@ -0,0 +1,249 @@ +# Good First Issue Guidelines + +This document defines what we **do** and **do not** consider a *Good First Issue (GFI)* in the Hiero Python SDK. + +## 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) +- [Maintainer Guidance](#-maintainer-guidance) + +--- + +## Purpose + +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 + +These issues are intentionally: + +- ✅ Small +- ✅ Low risk +- ✅ Easy to review +- ✅ Safe for first-time contributors + +--- + +## Allowed Categories + +### 🧵 Small, Focused Source Changes + +Limited, localized changes to existing source files that do not alter public behavior or SDK contracts. + +#### 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 + +--- + +### 🧩 Typing Improvements + +Improvements to type annotations that increase correctness or clarity without changing runtime behavior. + +#### Allowed + +- Adding missing return type hints +- Fixing incorrect or overly broad type annotations +- Resolving basic type conflicts flagged by type checkers + +#### Examples + +- 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 + +--- + +### 🔄 Refactors of Existing Examples + +Refactors that improve clarity, structure, or readability of **existing examples only**. + +#### Allowed + +- Refactoring an example for clarity or readability +- Extracting repeated logic into helper functions +- Renaming variables to be more descriptive + +#### Allowed Directions + +- Split a large example into smaller, named functions +- Combine a split example back into a single monolithic function for simplicity + +> ⚠️ **Note:** This category applies **only** to existing examples. +> Creating new examples is **out of scope** for GFIs. + +--- + +### 📚 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. + +#### Allowed + +- Improving clarity of `print()` statements +- Making output more descriptive or user-friendly +- Standardizing message formatting (prefixes, spacing, context) + +#### Examples + +- Replace ambiguous prints like `"Done"` with meaningful context +- Add explanatory text before printing values +- Make output ordering easier to follow + +--- + +### ⚙️ 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 + +#### Examples + +- Add an explicit setup step that was previously implied +- Improve error-handling clarity in an example +- Make control flow easier to follow + +--- + +### 🧪 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 + +- Creating new test files +- Designing new test strategies or frameworks + +Test creation often requires broader architectural context. + +--- + +### ❌ Core DLT or Protocol Logic + +- 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. + +--- + +### ❌ Cross-Cutting or Architectural Changes + +- Refactors spanning multiple modules or packages +- Changes requiring understanding of multiple subsystems +- Performance optimizations or concurrency changes + +These are better suited for experienced contributors. + +--- + +## 📌 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** +- ✅ Has **clear, well-defined scope** +- ✅ Requires **no domain or protocol knowledge** +- ✅ Can be **reviewed quickly** +- ✅ Has **low risk of breaking changes** + +### Do NOT label as GFI if the issue: + +- ❌ Touches **multiple subsystems** +- ❌ Changes **SDK behavior or contracts** +- ❌ Requires **domain or protocol knowledge** +- ❌ Could have **unintended side effects** +- ❌ Needs **extensive review or testing** + +### 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 + +--- + +## Additional Resources + +- [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_issues.md b/docs/maintainers/good_first_issues.md deleted file mode 100644 index e69de29bb..000000000