docs: advanced issue guidelines

[exploreriii]

Description:
Adds a guideline for advanced issues

Related issue(s):

Fixes #1327

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@           Coverage Diff           @@
##             main    #1331   +/-   ##
=======================================
  Coverage   92.29%   92.29%           
=======================================
  Files         139      139           
  Lines        8515     8515           
=======================================
  Hits         7859     7859           
  Misses        656      656           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds advanced issue guidelines documentation and updates the changelog. A new file defines criteria, examples, and maintainer guidance for Advanced Issues across multiple categories including source changes, architecture, typing, documentation, examples, and testing.

Changes

Cohort / File(s)	Summary
Documentation docs/maintainers/advanced-issue-guidelines.md	New comprehensive guideline document defining Advanced Issues with allowed/disallowed activities, criteria, examples, and maintainer labeling guidance across six categories
Changelog CHANGELOG.md	Added entry under Unreleased > Added section: "Added advanced issue template"

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Pre-merge checks

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Linked Issues check	❓ Inconclusive	The PR addresses the core objective from issue #1327 by creating the advanced issue guidelines documentation file, though some acceptance criteria (comprehensive tests, extensive examples/documentation updates) may not be fully evidenced.	Verify that comprehensive tests, examples, and documentation updates beyond the changelog entry are included to fully satisfy acceptance criteria from issue #1327.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: advanced issue guidelines' clearly and concisely describes the main change - adding documentation for advanced issue guidelines.
Description check	✅ Passed	The description 'Adds a guideline for advanced issues' directly relates to the changeset, which adds the advanced-issue-guidelines.md documentation file.
Out of Scope Changes check	✅ Passed	The PR contains only on-scope changes: adding the advanced-issue-guidelines.md documentation and a corresponding changelog entry, both directly aligned with issue #1327 requirements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ec903c7 and 8d2f479.

📒 Files selected for processing (2)

• CHANGELOG.md
• docs/maintainers/advanced-issue-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)

1. Verify code snippets conceptually run and match the current SDK API.
2. Check shell commands and workflow steps against actual project tooling.
3. Validate URLs and cross-references; flag broken or misleading links.

Priority 2 - Clarity and completeness

1. Ensure each page states its purpose and expected outcome early.
2. Prefer concrete, step-wise explanations over vague descriptions.
3. Highlight missing prerequisites that would block a reader.
4. For larger gaps, suggest filing a follow-up issue instead of blocking.

Priority 3 - Consistency and navigation

1. Encourage consistent terminology with the SDK and examples.
2. Check headings form a logical reading path.
3. 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/advanced-issue-guidelines.md

🪛 LanguageTool

docs/maintainers/advanced-issue-guidelines.md

[style] ~78-~78: Consider a different adjective to strengthen your wording.
Context: ...r abstractions - Bug fixes that require deep investigation across layers - Improveme...

(DEEP_PROFOUND)

🪛 markdownlint-cli2 (0.18.1)

docs/maintainers/advanced-issue-guidelines.md

174-174: Blank line inside blockquote

(MD028, no-blanks-blockquote)

⏰ 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 (2)

docs/maintainers/advanced-issue-guidelines.md (2)

27-49: Well-structured purpose statement with clear audience expectations.

The Purpose section (lines 27–49) clearly articulates the intent of Advanced Issues, explicitly names expected contributor skills, and sets realistic expectations. This aligns well with the PR objective to create guidelines analogous to the Good First Issues guidelines while targeting experienced contributors.

---

52-178: Comprehensive categorization and clear rule-of-thumb guidance.

The six categories (Source Changes, Architecture, Typing, Documentation, Examples, Testing) provide concrete decision boundaries with specific "Allowed" and "Not Allowed" patterns. The rule-of-thumb at line 169–177 gives maintainers a practical heuristic to distinguish Advanced Issues from Intermediate ones. This structure supports the goals stated in issue #1327.