docs: create beginner issue guidelines #1325
Conversation
Signed-off-by: exploreriii <[email protected]>
Signed-off-by: exploreriii <[email protected]>
Signed-off-by: exploreriii <[email protected]>
Signed-off-by: exploreriii <[email protected]>
Signed-off-by: exploreriii <[email protected]>
Signed-off-by: exploreriii <[email protected]>
Signed-off-by: exploreriii <[email protected]>
Codecov Report✅ All modified and coverable lines are covered by tests. @@ Coverage Diff @@
## main #1325 +/- ##
=======================================
Coverage 92.29% 92.29%
=======================================
Files 139 139
Lines 8515 8515
=======================================
Hits 7859 7859
Misses 656 656 🚀 New features to boost your workflow:
|
📝 WalkthroughWalkthroughReorganized and refactored Good First Issue (GFI) and GFI-Candidate guidance, introduced a new Beginner Issues category, removed the legacy GFI doc, updated issue templates to reference new maintainer guidelines, and standardized assignment wording to “get assigned by commenting Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Pre-merge checks✅ Passed checks (5 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.github/ISSUE_TEMPLATE/01_good_first_issue_candidate.yml (1)
19-19: Broken link: Incorrect path to guidelines document.The referenced path
docs/maintainers/good_first_issue_guidelines.mdis incorrect. Based on the files in this PR, the correct path should bedocs/maintainers/good_first_issues_guidelines.md(note the 's' in "issues").🔎 Proposed fix
- > docs/maintainers/good_first_issue_guidelines.md + > docs/maintainers/good_first_issues_guidelines.md
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (8)
.github/ISSUE_TEMPLATE/01_good_first_issue_candidate.yml.github/ISSUE_TEMPLATE/04_good_first_issue.ymlCHANGELOG.mddocs/GFI/GFI-Guidelines.mddocs/GFI/GFI-Management.mddocs/maintainers/beginner-issues-guidelines.mddocs/maintainers/good_first_issue_candidate_guidelines.mddocs/maintainers/good_first_issues_guidelines.md
💤 Files with no reviewable changes (1)
- docs/GFI/GFI-Guidelines.md
🧰 Additional context used
📓 Path-based instructions (1)
docs/**
⚙️ CodeRabbit configuration file
docs/**: You are reviewing documentation for the Hiero Python SDK. These pages serve both SDK users and SDK developers.Priority 1 - Correctness (code, commands, links)
- Verify code snippets conceptually run and match the current SDK API.
- Check shell commands and workflow steps against actual project tooling.
- Validate URLs and cross-references; flag broken or misleading links.
Priority 2 - Clarity and completeness
- Ensure each page states its purpose and expected outcome early.
- Prefer concrete, step-wise explanations over vague descriptions.
- Highlight missing prerequisites that would block a reader.
- For larger gaps, suggest filing a follow-up issue instead of blocking.
Priority 3 - Consistency and navigation
- Encourage consistent terminology with the SDK and examples.
- Check headings form a logical reading path.
- Confirm each page makes clear which audience it serves.
PHILOSOPHY
- Treat docs as work-in-progress: optimize for correctness and clarity over perfection.
- Keep feedback concise, action-oriented, and focused on reader success.
- Do not request large-scale restructures unless current structure blocks understanding.
AVOID
- Avoid lint-style feedback on Markdown formatting or minor wording.
- Avoid proposing new conventions without clear benefit.
- Avoid turning every high-level gap into a blocker.
Files:
docs/GFI/GFI-Management.mddocs/maintainers/good_first_issue_candidate_guidelines.mddocs/maintainers/beginner-issues-guidelines.mddocs/maintainers/good_first_issues_guidelines.md
🪛 LanguageTool
docs/maintainers/beginner-issues-guidelines.md
[grammar] ~36-~36: Use a hyphen to join words.
Context: ...workflow - Basic Git - At least beginner level programming - Reading and navigati...
(QB_NEW_EN_HYPHEN)
docs/maintainers/good_first_issues_guidelines.md
[style] ~43-~43: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...utors Importantly, they have: - ✅ A **very clear, explicitly described, or provided solu...
(EN_WEAK_ADJECTIVE)
[style] ~56-~56: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ... Allowed (rare, explicit cases only) - Very small, explicitly described edits to existing...
(EN_WEAK_ADJECTIVE)
[grammar] ~89-~89: Ensure spelling is correct
Context: ...instruction-driven*. #### Allowed - Remaing variable names when new names are provi...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🪛 markdownlint-cli2 (0.18.1)
docs/maintainers/good_first_issue_candidate_guidelines.md
58-58: Link text should be descriptive
(MD059, descriptive-link-text)
73-73: Link text should be descriptive
(MD059, descriptive-link-text)
125-125: Link text should be descriptive
(MD059, descriptive-link-text)
docs/maintainers/beginner-issues-guidelines.md
134-134: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
134-134: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
135-135: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
139-139: Blank line inside blockquote
(MD028, no-blanks-blockquote)
147-147: Heading levels should only increment by one level at a time
Expected: h3; Actual: h4
(MD001, heading-increment)
docs/maintainers/good_first_issues_guidelines.md
11-11: Link fragments should be valid
(MD051, link-fragments)
13-13: Link fragments should be valid
(MD051, link-fragments)
14-14: Link fragments should be valid
(MD051, link-fragments)
49-49: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Above
(MD022, blanks-around-headings)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (4)
docs/GFI/GFI-Management.md (1)
158-158: Verify consistency of GFI document path references.Line 158 correctly updates the reference to
docs/maintainers/good_first_issues_guidelines.md. However, line 149 referencesGFI-frequency.mdwithout a path prefix. Confirm whether this file has also been moved to the new structure or remains in its original location.docs/maintainers/beginner-issues-guidelines.md (3)
1-40: Purpose and structure are clear; audience expectations are well-defined.The document correctly positions Beginner Issues as the intermediate step between Good First Issues and advanced work. The purpose section (lines 24–38) clearly states the intended audience and their assumed baseline knowledge, which helps maintainers apply the label consistently.
41-133: Categories and examples effectively define scope and prevent scope creep.The five categories (Source Changes, Typing, Documentation, Examples, Tests) with concrete Allowed/Not Allowed examples provide clear, actionable guidance for maintainers. Boundaries like "no cross-cutting changes," "no new test suites," and "no large documentation workflows" are well-reasoned and help maintain the "beginner" scope.
160-166: Verify that all resource links resolve correctly.The Additional Resources section references several internal and external links. Confirm:
docs/maintainers/good_first_issues_guidelines.mdexists (per PR description, it should)../../CONTRIBUTING.mdand other relative paths resolve fromdocs/maintainers/- External Zoom link (
https://zoom-lfx.platform.linuxfoundation.org/meetings/hiero?view=week) is current and accessibleAs per coding guidelines Priority 1, broken or misleading links should be flagged.
Signed-off-by: exploreriii <[email protected]>
Signed-off-by: exploreriii <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (4)
docs/maintainers/good_first_issue_candidate_guidelines.md (4)
58-58: Use descriptive link text for better clarity and accessibility.The link text "GFIC Guidelines" uses an undefined acronym. This was previously flagged but not yet addressed.
🔎 Proposed fix
-Suitability can be assessed [GFIC Guidelines](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/maintainers/good_first_issues_guidelines.md) +Suitability can be assessed in the [Good First Issue Guidelines](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/maintainers/good_first_issues_guidelines.md)
73-73: Use descriptive link text instead of "here".Using "here" as link text is not descriptive and was previously flagged. Descriptive link text improves accessibility and clarity.
🔎 Proposed fix
-Check by reading good first issue guidelines [here](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/maintainers/good_first_issues_guidelines.md) +Check by reading the [Good First Issue Guidelines](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/maintainers/good_first_issues_guidelines.md)
75-75: Fix grammatical error with double "are".This sentence has a grammatical error that was previously flagged but not yet addressed.
🔎 Proposed fixes
Option 1:
-If easy issues are not 'Good First Issues' are in fact 'beginner' issues. +If easy issues are not 'Good First Issues', they are in fact 'beginner' issues.Option 2:
-If easy issues are not 'Good First Issues' are in fact 'beginner' issues. +Easy issues that are not 'Good First Issues' are in fact 'beginner' issues.
125-125: Remove redundant link or restructure for clarity.The link text "here" was previously flagged as not descriptive. Since "Good First Issue Guidelines" already appears in the sentence, the link text "here" is redundant.
🔎 Proposed fix
-1. Review the issue against the **Good First Issue Guidelines** [here](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/maintainers/good_first_issues_guidelines.md) +1. Review the issue against the [Good First Issue Guidelines](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/maintainers/good_first_issues_guidelines.md)
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (4)
.github/ISSUE_TEMPLATE/01_good_first_issue_candidate.yml.github/ISSUE_TEMPLATE/04_good_first_issue.ymldocs/maintainers/good_first_issue_candidate_guidelines.mddocs/maintainers/good_first_issues_guidelines.md
🧰 Additional context used
📓 Path-based instructions (1)
docs/**
⚙️ CodeRabbit configuration file
docs/**: You are reviewing documentation for the Hiero Python SDK. These pages serve both SDK users and SDK developers.Priority 1 - Correctness (code, commands, links)
- Verify code snippets conceptually run and match the current SDK API.
- Check shell commands and workflow steps against actual project tooling.
- Validate URLs and cross-references; flag broken or misleading links.
Priority 2 - Clarity and completeness
- Ensure each page states its purpose and expected outcome early.
- Prefer concrete, step-wise explanations over vague descriptions.
- Highlight missing prerequisites that would block a reader.
- For larger gaps, suggest filing a follow-up issue instead of blocking.
Priority 3 - Consistency and navigation
- Encourage consistent terminology with the SDK and examples.
- Check headings form a logical reading path.
- Confirm each page makes clear which audience it serves.
PHILOSOPHY
- Treat docs as work-in-progress: optimize for correctness and clarity over perfection.
- Keep feedback concise, action-oriented, and focused on reader success.
- Do not request large-scale restructures unless current structure blocks understanding.
AVOID
- Avoid lint-style feedback on Markdown formatting or minor wording.
- Avoid proposing new conventions without clear benefit.
- Avoid turning every high-level gap into a blocker.
Files:
docs/maintainers/good_first_issue_candidate_guidelines.mddocs/maintainers/good_first_issues_guidelines.md
🪛 LanguageTool
docs/maintainers/good_first_issues_guidelines.md
[style] ~40-~40: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...utors Importantly, they have: - ✅ A **very clear, explicitly described, or provided solu...
(EN_WEAK_ADJECTIVE)
[style] ~53-~53: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ... Allowed (rare, explicit cases only) - Very small, explicitly described edits to existing...
(EN_WEAK_ADJECTIVE)
🪛 markdownlint-cli2 (0.18.1)
docs/maintainers/good_first_issues_guidelines.md
73-73: Link text should be descriptive
(MD059, descriptive-link-text)
125-125: Link text should be descriptive
(MD059, descriptive-link-text)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (7)
- GitHub Check: Codacy Static Code Analysis
- GitHub Check: build-and-test (3.10)
- GitHub Check: build-and-test (3.13)
- GitHub Check: build-and-test (3.12)
- GitHub Check: build-and-test (3.11)
- GitHub Check: run-examples
- GitHub Check: StepSecurity Harden-Runner
Signed-off-by: exploreriii <[email protected]>
Signed-off-by: exploreriii <[email protected]>
Signed-off-by: exploreriii <[email protected]> feat: add GFI candidate notification bot with dry-run support Signed-off-by: Parv <[email protected]> fix: prevent runtime error by defining dryRun from process.env Signed-off-by: Parv <[email protected]>
2 participants
Description:
This creates guidelines for beginner issues
Thus also updates good first issues and good first issue candidate guidelines and templates
Related issue(s):
Fixes #1324
Notes for reviewer:
Tested here
exploreriii#86
exploreriii#85