🧑‍💻 Intermediate Issue

Welcome! This is an Intermediate Issue touching core SDK architecture.

🏁 When this issue is complete, you will have:

✅ Researched across multiple files and modules
✅ Owned implementation decisions
✅ Written thorough, meaningful tests
✅ Delivered a clean, review-ready pull request

🐞 Problem Description

The repository currently maintains separate GitHub Actions workflows and scripts for automatically assigning contributors to beginner and good-first-issue (GFI) issues.

.github/workflows/bot-gfi-assign-on-comment.yml
.github/workflows/bot-beginner-assign-on-comment.yml

These workflows contain overlapping logic and require independent maintenance. As the automation evolves, changes often need to be implemented in multiple locations, increasing the risk of inconsistent behavior and duplicated code.

Additionally, automatic assignment support is currently limited to beginner and GFI issues. Intermediate and advanced issues do not participate in the same automated assignment flow, resulting in inconsistent contributor experiences across issue difficulty levels.

💡 Expected Solution

Implement a consolidated assignment automation solution that replaces duplicated beginner and GFI assignment logic with a shared implementation.

The resulting solution should preserve existing assignment behavior for beginner and GFI issues while providing a clear path for supporting intermediate and advanced issue assignment workflows.

🔍 Background Research

.github/workflows/bot-gfi-assign-on-comment.js
.github/workflows/bot-gfi-assign-on-comment.yml
.github/workflows/bot-beginner-assign-on-comment.js
.github/workflows/bot-beginner-assign-on-comment.yml

🔬 Technical Domains

• Intermediate to Advanced Programming (Object oriented design, inheritance, complex type systems)
• File Specific Knowledge (request → serialization → execution → response mapping)
• Backward Compatibility (preserving method signatures, defaults, and return types)
• Protobuf Alignment (reading .proto files, _to_proto() / _from_proto() correctness)
• Testing (unit, integration, mocking, test coverage for edge cases and failure modes)

🧠 Intermediate Contributors — Prerequisites & Expectations

🏁 Concrete Prerequisites

• Advanced Programming Language: Higher level intermediate or advanced programming language.
• Expertise: Strong understanding of files related to this issue (research before claiming!).
• Proven History: Successfully completed ≥ 5 beginner issues in this repo.

If this feels like too big a step, that is completely fine — try a Beginner Issue first or a different Intermediate Issue. You can always come back when you are ready.

⚠️ AI Usage Policy

• Using AI to generate code for Intermediate issues is strictly discouraged
• Using AI as the main source of research is strictly discouraged, refer to language and library documentation, protobuf definitions and other SDKs.

⏱️ Timeline & Workflow

• Typical time: ~2 weeks / ~25 hours.
• 🔴 Completing an intermediate issue in 1–3 days is a red flag.

🧪 Testing Requirements

How you test depends on the type of change.

Source code changes (e.g. in src/):

• Write unit tests covering happy path, edge cases, and error handling
• Run tests locally: uv run pytest tests/unit/<specific_file>_test.py -v
• Verify naming, types, and field ordering match protobuf definitions
• Check consistency with similar classes already in the SDK — use the same patterns
• Integration tests will run automatically when you push

GitHub Actions / workflow changes (e.g. in .github/): Guide

• Test by merging to your fork's main and simulating the scenario
• Create test issues or PRs as evidence and link them in your PR
• Include screenshots of workflow runs where applicable

Example script changes (e.g. in examples/):

• Run the example script and confirm output matches expected behavior
• Compare your example with similar existing examples for consistency
• You will need a Hedera Portal account for testnet credentials

🛡️ Quality & Review Standards

Intermediate PRs must be "working, maintainable, and aligned with SDK architecture."

1. Working: The implementation must solve the problem and meet the acceptance criteria.
2. Maintainable: Code should be clear and concise enough for others to understand and debug without your assistance.
3. SDK Alignment: The solution should fit well with existing SDK patterns and abstractions.
4. Backward Compatibility: Public API signatures must be preserved.
5. Comprehensive Testing: Must include unit and integration tests covering all new logic paths, edge cases, and failure modes. AI generated tests based on AI generated code is grounds for immediate rejection.

⚠️ Breaking changes

• Before changing any function signature, return type, or public API — stop and check
• If a breaking change is unavoidable: get explicit maintainer approval before implementing
• All existing tests should pass as-is.

🤖 AI notes

• AI often has outdated real-world knowledge: it will not be able to identify current packages.
• AI has gaps or incorrect understanding of repo-specific patterns, logic, and protobuf schemes.

✅ PR Quality Checklist

Before opening your PR, confirm:

• I have spent the majority of my time researching the problem and solution space extensively, including reviewing relevant code, documentation, and external resources.
• My implementation works but is also of high quality - including maintainability, readability, and architectural fit.
• I have checked for breaking changes - no public APIs regress.
• The system design fits with current Hiero SDK architectural approaches.
• Every line of code is personally understood and explainable.

Before requesting a review, confirm:

• I have reviewed the diff line by line.
• My implementation fully addresses the problem described above.
• I did not modify files unrelated to this issue
• Clean git history — no rebase artifacts, merge commits, or unrelated files
• My commits are signed: git commit -S -s -m "chore: description" — Signing guide
• I have verified naming, types, and field ordering against pinned Protobufs.
• I have applied appropriate linting, code quality, and formatting tools used in this repo.
• I have included appropriate tests and all CI checks pass.
• Double and triple check — intermediate PRs are time-consuming to review

📋 Workflow quick reference

You know the workflow — here are the links if you need them:

Step	Guide
Claim this issue	Comment /assign below
Sync with main	Rebasing guide
Open a PR and link this issue	PR guide · Linking guide
Resolve merge conflicts	Merge conflicts guide
Testing	Testing guide

📚 Resources & Support

🆘 Stuck?

Project references:

• Project structure
• CONTRIBUTING.md
• Browse closed intermediate PRs — see how others did it
• Pylance guide

Protobuf references:

• Hedera Protobufs — source of truth for field names, types, and ordering
• Protobuf language guide

Python references:

• Python official docs
• Data model (dunder methods)
• Type hints
• unittest.mock — for mocking in tests

Community:

• Community Calls
• Discord