Create document on PR review guidelines

[exploreriii]

🧑‍🎓 Beginner Issue

Welcome! This is a Beginner Issue designed to help you learn the codebase.

🏁 When this issue is complete, you will have:

✅ Researched a file or method in detail
✅ Followed SDK patterns to implement a solution
✅ Researched and identified appropriate programming constructs to solve the problem
✅ Created basic tests
✅ Delivered a clean, review-ready pull request

🐞 Problem Description

We have recently added a label that indicates a pull request is ready for community review - open to anybody in the community to review:
https://github.com/hiero-ledger/hiero-sdk-python/pulls?q=is%3Aopen+is%3Apr+label%3A%22reviewer%3A+community%22

We want to create a document outlining best practice guidelines at
/docs

💡 Expected Solution

Create a best practice guide for reviewing pull requests

🔍 Research Pointers

Here are merged PRs to review how they are reviewed:
https://github.com/hiero-ledger/hiero-sdk-python/pulls?q=is%3Apr+is%3Aclosed+is%3Amerged

🛠️ Implementation Notes

To create a best practice guide we should outline:

• Anyone from the community is welcome to provide reviews on label: review community
• What we look for in a review:
  pull request meets checks:

Quality

• GPG key signed?
• DCO signed?
• Is the PR linked to the issue?
• Does the PR solve the issue?
• Do all the workflow checks pass? If not, what is the document to point them in the right direction?

When doing a review:

• operate mostly within your circle of competence, but do stretch yourself
• Frame things as a question if not sure, be aware people might take any suggestions literally without thinking, so frame things as a question unless you are sure they should change something
• always study the issue description
• study the code submitted, open it in a github workspace and check it etc
• check for language issues too
• try not to take AI review suggestions literally, they could be totally wrong -- think first

etc

🧠 Beginner Contributors — Prerequisites & Expectations

Caution

Beginner issues are low-risk but we expect a working solution.

Important

We recommend completing at least 3 Good First Issues before attempting a beginner issue.

Difficulty:

• Requires building knowledge of the specific file(s)
• Beginner to intermediate Coding skills

Tip

You should be comfortable with:

• Forking, branching, committing (with DCO + GPG signing), and opening a pull request without a tutorial
• Reading beginner to intermediate code you did not write and following its patterns
• Handling simple merge conflicts
• Keeping your fork up to date with main by rebasing
• Looking things up on your own before asking for help

If any of that feels unfamiliar, Good First Issues might still be the most rewarding path for you right now — find one here.
You can always come back when you are ready.

⚠️ AI Usage Policy

• AI can help you understand the codebase and the problem
• Using AI to generate code for beginner 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: ~1 Week / ~8 hours.
  🧩 Difficulty: Manageable but requires investigation and testing
  🎓 Best for: Beginner contributors

• 🔴 Completing a beginner issue in 1–3 hours is a red flag.

Tip

Suggested: share your proposed implementation approach as a comment before writing code to get early feedback and avoid wasted effort.

🧪 Testing Requirements

Important

At the beginner level, testing will be necessary but a small component.
The methods you implement should be verified (happy path at least)

How you test depends on the type of change.

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

• Write basic unit tests
• Run tests locally: uv run pytest tests/unit/<specific_file>_test.py -v
• 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

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

• Run the example script and confirm output matches expected behavior
• You will need a Hedera Portal account for testnet credentials

🛡️ Quality & Review Standards

Beginner PRs must be working and follow best practices.

1. Working: The implementation must solve the problem and meet the acceptance criteria.
2. SDK Best Practices: The solution should fit well with existing SDK patterns and abstractions.
3. Testing: basic unit and possibly integration tests to demonstrate the implementation works as expected.

⚠️ Breaking changes

• Watch for any changes that could impact existing users, even if they seem small.

🤖 AI notes

• 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 building my understanding of the codebase and methods.
• My implementation works and is tested (if applicable).
• Every line of code is personally understood and explainable.
• My changes address what the issue asked for — nothing more, nothing less
• I have applied appropriate linting, code quality, and formatting tools used in this repo.

Before requesting a review, confirm:

• 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 included appropriate tests and all CI checks pass.

📋 Workflow quick reference

You have done this before — 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
Resolve merge conflicts	Merge conflicts guide

📚 Resources & Support

🆘 Stuck?

Tip

Comment on this issue: and describe what you have tried. A maintainer will respond.

Python SDK References:

• Windows Setup Guide — platform-specific installation steps
• Pylance guide — inline type checking during development
• Running examples
• Browse closed beginner PRs — see how others did it

References:

• Hedera Protobufs
• Community Calls
• Discord

[github-actions]

@coderabbitai plan

[sudo-anshul]

hi @exploreriii i would like to work on this issue!

[coderabbitai]

Coding Plan

Summary

• Create a single new Markdown file following the established documentation style in docs/sdk_developers/
• Structure content around the two main themes: quality verification checks and review behavior guidelines
• Use existing patterns (numbered sections, DO/DON'T lists, emoji icons, cross-references) for consistency
• Include all specific guidance items mentioned in the ticket while organizing them into logical, scannable sections

Implementation Steps

Create PR Review Guidelines Document

Create a new documentation file that provides community members with comprehensive guidance for reviewing pull requests labeled reviewer: community, following established documentation patterns in the repository.

Task 1: Create Document Structure

Set up the document with standard formatting following existing patterns in docs/sdk_developers/.

• Create new file docs/sdk_developers/pr_review_guidelines.md
• Add H1 title: # PR Review Guidelines
• Add Table of Contents section with anchor links to all major sections
• Use horizontal rules (---) to separate major sections
• Use numbered H2 sections for sequential organization

Task 2: Write Introduction and Community Welcome Section

Establish the purpose of the document and welcome community reviewers.

• Add introduction explaining the reviewer: community label and its purpose
• Link to the filtered PR list: https://github.com/hiero-ledger/hiero-sdk-python/pulls?q=is%3Aopen+is%3Apr+label%3A%22reviewer%3A+community%22
• Welcome message encouraging community participation in reviews
• Brief overview of what the document covers

Task 3: Write Quality Checks Section

Document the verification steps reviewers should perform for each PR.

• GPG Signing: Explain how to verify commits are GPG-signed (look for "Verified" badge on commits), link to docs/sdk_developers/training/workflow/07_signing_requirements.md
• DCO Sign-off: Explain the Signed-off-by line requirement, link to signing documentation
• Issue Linkage: Check PR description for closes #, fixes #, or resolves # references
• Issue Resolution: Verify the PR actually solves what the linked issue describes
• CI Workflow Checks: List the primary and secondary checks that should pass:
  • Primary: Code-coverage, CodeQL, Broken Markdown Links, Test Files Naming
  • Secondary: Unit/Integration Tests, Dependency Compatibility, Examples, TCK Tests
• Include links to relevant guides when checks fail (reference the workflow failure bot's suggested links)

Task 4: Write Review Best Practices Section

Document behavioral guidelines for conducting effective reviews.

• Circle of Competence: Encourage reviewers to focus on areas they understand well, but also stretch themselves to learn
• Communication Style:
  • Frame uncertain feedback as questions rather than directives
  • Explain that contributors may take suggestions literally without critical evaluation
  • Use constructive, respectful language (cross-reference code_of_conduct.md)
• Research Process:
  • Always read the full issue description first
  • Study the submitted code thoroughly
  • Suggest opening in GitHub Codespaces or locally for complex changes
• Language and Documentation: Check for typos, grammar issues, and documentation quality
• AI Review Caution:
  • Don't accept AI-generated review suggestions without critical thinking
  • AI tools may not understand repo-specific patterns or context
  • Verify any AI suggestions against actual codebase patterns

Task 5: Write DO/DON'T Reference Section

Add a scannable checklist using the DO/DON'T pattern from testing.md.

• Use ### DO ✅ format with bullet points for recommended behaviors
• Use ### DON'T ❌ format with bullet points for behaviors to avoid
• Include key items from the review best practices in checklist form
• Keep items concise and actionable

Task 6: Add Cross-References and Help Section

Complete the document with helpful links and resources.

• Add "Related Documentation" section linking to:
  • workflow.md — Contribution workflow
  • testing.md — Testing guidelines and checklist
  • code_of_conduct.md — Community standards
  • CONTRIBUTING.md — Main contribution entry point
  • training/workflow/10_submit_pull_request.md — PR submission details
• Add "Need Help?" footer section following existing pattern with links to:
  • Discord channel
  • Community calls
  • How to ask questions on issues

🤖 Prompt for AI agents

Create a new Markdown file at `docs/sdk_developers/pr_review_guidelines.md`
following the established documentation style used across the other 41 files in
that directory. The goal is a comprehensive PR review guide for community
reviewers.

**Document Structure & Formatting:**
- H1 title: `# PR Review Guidelines`
- Table of Contents with anchor links to all major sections
- Numbered H2 sections for sequential organization
- Horizontal rules (`---`) to separate major sections
- H3 subsections where needed
- Emoji icons (✅/❌/⚠️) following existing patterns

**Section 1 — Introduction & Community Welcome:**
- Explain the `reviewer: community` label and its purpose
- Link to the filtered PR list:
`https://github.com/hiero-ledger/hiero-sdk-python/pulls?q=is%3Aopen+is%3Apr+label%3A%22reviewer%3A+community%22`
- Include a welcome message encouraging community participation
- Brief overview of what the document covers

**Section 2 — Quality Checks:**
- **GPG Signing**: How to verify commits are GPG-signed (look for "Verified"
badge), link to
`docs/sdk_developers/training/workflow/07_signing_requirements.md`
- **DCO Sign-off**: Explain the `Signed-off-by` line requirement, link to
signing documentation
- **Issue Linkage**: Check PR description for `closes #`, `fixes #`, or
`resolves #` references
- **Issue Resolution**: Verify the PR actually solves what the linked issue
describes
- **CI Workflow Checks** listing:
  - Primary: Code-coverage, CodeQL, Broken Markdown Links, Test Files Naming
- Secondary: Unit/Integration Tests, Dependency Compatibility, Examples, TCK
Tests
- Include links to relevant guides when checks fail (reference the workflow
failure bot's suggested links)

**Section 3 — Review Best Practices:**
- **Circle of Competence**: Focus on areas of understanding, but also stretch to
learn
- **Communication Style**: Frame uncertain feedback as questions, note
contributors may take suggestions literally, use constructive/respectful
language, cross-reference `code_of_conduct.md`
- **Research Process**: Read full issue description first, study submitted code
thoroughly, suggest opening in GitHub Codespaces or locally for complex changes
- **Language and Documentation**: Check for typos, grammar issues, and
documentation quality
- **AI Review Caution**: Don't accept AI-generated suggestions without critical
thinking, AI may not understand repo-specific patterns, verify AI suggestions
against actual codebase patterns

**Section 4 — DO/DON'T Reference Checklist:**
- Use `### DO ✅` format with bullet points for recommended behaviors
- Use `### DON'T ❌` format with bullet points for behaviors to avoid
- Draw key items from the review best practices section
- Keep items concise and actionable

**Section 5 — Related Documentation & Help:**
- "Related Documentation" subsection linking to:
  - `workflow.md` — Contribution workflow
  - `testing.md` — Testing guidelines and checklist
  - `code_of_conduct.md` — Community standards
  - `CONTRIBUTING.md` — Main contribution entry point
  - `training/workflow/10_submit_pull_request.md` — PR submission details
- "Need Help?" footer section (following existing pattern in the directory) with
links to Discord channel, community calls, and how to ask questions on issues

Research

The docs/sdk_developers/ directory contains 41 Markdown files following a consistent style: H1 titles, optional Table of Contents with anchor links, numbered H2 sections, H3 subsections, horizontal rule dividers, emoji icons (✅/❌/⚠️), DO/DON'T lists, and a "Need Help?" footer. Related existing docs include workflow.md (contribution workflow), testing.md (testing checklist), and training/workflow/10_submit_pull_request.md (PR submission details). The repository has comprehensive CI workflows including primary checks (code coverage, CodeQL, broken links, test file naming) and secondary checks (unit/integration tests, dependency compatibility, examples). GPG and DCO signing are expected practices though the automated enforcement is currently archived.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Create a new Markdown file at `docs/sdk_developers/pr_review_guidelines.md`
following the established documentation style used across the other 41 files in
that directory. The goal is a comprehensive PR review guide for community
reviewers.

**Document Structure & Formatting:**
- H1 title: `# PR Review Guidelines`
- Table of Contents with anchor links to all major sections
- Numbered H2 sections for sequential organization
- Horizontal rules (`---`) to separate major sections
- H3 subsections where needed
- Emoji icons (✅/❌/⚠️) following existing patterns

**Section 1 — Introduction & Community Welcome:**
- Explain the `reviewer: community` label and its purpose
- Link to the filtered PR list:
`https://github.com/hiero-ledger/hiero-sdk-python/pulls?q=is%3Aopen+is%3Apr+label%3A%22reviewer%3A+community%22`
- Include a welcome message encouraging community participation
- Brief overview of what the document covers

**Section 2 — Quality Checks:**
- **GPG Signing**: How to verify commits are GPG-signed (look for "Verified"
badge), link to
`docs/sdk_developers/training/workflow/07_signing_requirements.md`
- **DCO Sign-off**: Explain the `Signed-off-by` line requirement, link to
signing documentation
- **Issue Linkage**: Check PR description for `closes #`, `fixes #`, or
`resolves #` references
- **Issue Resolution**: Verify the PR actually solves what the linked issue
describes
- **CI Workflow Checks** listing:
  - Primary: Code-coverage, CodeQL, Broken Markdown Links, Test Files Naming
- Secondary: Unit/Integration Tests, Dependency Compatibility, Examples, TCK
Tests
- Include links to relevant guides when checks fail (reference the workflow
failure bot's suggested links)

**Section 3 — Review Best Practices:**
- **Circle of Competence**: Focus on areas of understanding, but also stretch to
learn
- **Communication Style**: Frame uncertain feedback as questions, note
contributors may take suggestions literally, use constructive/respectful
language, cross-reference `code_of_conduct.md`
- **Research Process**: Read full issue description first, study submitted code
thoroughly, suggest opening in GitHub Codespaces or locally for complex changes
- **Language and Documentation**: Check for typos, grammar issues, and
documentation quality
- **AI Review Caution**: Don't accept AI-generated suggestions without critical
thinking, AI may not understand repo-specific patterns, verify AI suggestions
against actual codebase patterns

**Section 4 — DO/DON'T Reference Checklist:**
- Use `### DO ✅` format with bullet points for recommended behaviors
- Use `### DON'T ❌` format with bullet points for behaviors to avoid
- Draw key items from the review best practices section
- Keep items concise and actionable

**Section 5 — Related Documentation & Help:**
- "Related Documentation" subsection linking to:
  - `workflow.md` — Contribution workflow
  - `testing.md` — Testing guidelines and checklist
  - `code_of_conduct.md` — Community standards
  - `CONTRIBUTING.md` — Main contribution entry point
  - `training/workflow/10_submit_pull_request.md` — PR submission details
- "Need Help?" footer section (following existing pattern in the directory) with
links to Discord channel, community calls, and how to ask questions on issues

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[github-actions]

👋 Hi @sudo-anshul! If you'd like to work on this issue, please comment /assign to get assigned.

[sudo-anshul]

/assign

[github-actions]

👋 Hi @sudo-anshul! Thanks for your interest in contributing 💡

Before taking on a beginner issue, we ask contributors to complete at least one Good First Issue to get familiar with the workflow.

👉 Find a Good First Issue here

Please try a GFI first, then come back — we’ll be happy to assign this! 😊

[YYuan02]

/assign

[github-actions]

Hi @YYuan02 — this issue is already assigned to @sudo-anshul, so I can’t assign it again.

👉 Choose a different Good First Issue to work on next:
Browse unassigned Good First Issues

Once you find one you like, comment /assign to get started.

[github-actions]

Hi @sudo-anshul 👋

This issue has been assigned but no pull request has been created yet.
Are you still planning on working on it?
If you are, please create a draft PR linked to this issue or comment /working to let us know.
If you’re no longer able to work on this issue, you can comment /unassign to release it.

From the Python SDK Team

[sudo-anshul]

/working