feat: Add Workflow Documentation Guide

[jona42-ui]

Description:

This commit adds a comprehensive guide for documenting GitHub workflows and automation scripts . The guide covers best practices for:

• Writing clear header blocks with PURPOSE, TRIGGER, MAJOR RULES, and RELATED DOCS
• Creating informative docstrings explaining intent, assumptions, side effects, and edge cases
• Making exit reasons obvious with clear comments
• Using descriptive, action-oriented naming conventions

The guide includes practical examples in Javascript, a documentation checklist, and links to related documentation.

Related issue(s):

Fixes #1745

Notes for reviewer:

Checklist

• Documented (Code comments, README, etc.)
• Tested (unit, integration, etc.)

[github-actions]

Hi @jona42-ui, this is **LinkBot** 👋

Linking pull requests to issues helps us significantly with reviewing pull requests and keeping the repository healthy.

🚨 This pull request does not have an issue linked.

Please link an issue using the following format:

• Fixes chore: [StepSecurity] Apply security best practices #123

📖 Guide:
docs/sdk_developers/how_to_link_issues.md

If no issue exists yet, please create one:
docs/sdk_developers/creating_issues.md

Thanks!

[coderabbitai]

Walkthrough

Adds a new Workflow Documentation Guide at docs/github/04_workflow_documentation.md and a corresponding changelog entry in CHANGELOG.md. The guide prescribes header structure, docstring standards, exit-reason comments, naming conventions, examples, and a documentation checklist.

Changes

Cohort / File(s)	Summary
Documentation guide & changelog CHANGELOG.md, docs/github/04_workflow_documentation.md	Adds a new documentation file describing how to document GitHub workflows and automation scripts (header blocks, docstring conventions, exit-reason comments, naming guidance, examples, and a checklist). Updates changelog with the new documentation entry.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding a workflow documentation guide.
Description check	✅ Passed	The description is related to the changeset, covering best practices for documenting workflows and linking to the related issue.
Linked Issues check	✅ Passed	The PR comprehensively addresses issue #1745 requirements: includes top-of-file header guidance (PURPOSE, TRIGGER, MAJOR RULES, RELATED DOCS), documents docstring best practices (intent, assumptions, side effects, edge cases), emphasizes explicit exit reasons, promotes clear naming conventions, includes practical examples, and adds a changelog entry.
Out of Scope Changes check	✅ Passed	All changes are in scope: the new documentation file and changelog entry directly fulfill issue #1745 objectives with no extraneous modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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.}

[Copilot]

Pull request overview

Adds a new documentation guide describing best practices for documenting GitHub workflows and automation scripts in the Hiero Python SDK, addressing the need captured in issue #1745.

Changes:

• Added a new workflow documentation guide under docs/github/.
• Added a changelog entry documenting the new guide.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
docs/github/04_workflow_documentation.md	Introduces a workflow documentation best-practices guide with examples, checklist, and related links.
CHANGELOG.md	Records the addition of the workflow documentation guide under the Documentation section.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 3

[coderabbitai]

Actionable comments posted: 1

[aceppaluni]

@jona42-ui Thank you for your contribution!

A few tweaks:

1. The check for the PR title is failing. To correct this change to feat: Add Workflow Documentation Guide
2. Please take a look at the AI/Coderabbit suggestions. There is a mention of unused imports and correct the description.

If you have questions please reach out. We're happy to help!

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@           Coverage Diff           @@
##             main    #1772   +/-   ##
=======================================
  Coverage   93.29%   93.29%           
=======================================
  Files         141      141           
  Lines        9118     9118           
=======================================
  Hits         8507     8507           
  Misses        611      611           

🚀 New features to boost your workflow:

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

[aceppaluni]

@jona42-ui Great work, thank you for the corrections!

LGTM!

Note

You can ignore the failing check.
This happens when the integration tests take longer then 7 minutes to run.

[MonaaEid]

It seems the documentation doesn’t fully meet the issue requirements, so please review them carefully... Thank you!

[github-actions]

Hello, this is the OfficeHourBot.

This is a reminder that the Hiero Python SDK Office Hours are scheduled in approximately 4 hours (14:00 UTC).

This session provides an opportunity to ask questions regarding this Pull Request.

Details:

• Time: 14:00 UTC
• Join Link: Zoom Meeting

Disclaimer: This is an automated reminder. Please verify the schedule here for any changes.

From,
The Python SDK Team

[MonaaEid]

Please take a look at the workflows and scripts Scripts,
Workflows
I think the docs should describe what we already use.

[MonaaEid]

Hi @jona42-ui, if you need help with that or have any questions, feel free to reach out. ...we're happy to help, thank you!

[jona42-ui]

Please take a look at the workflows and scripts Scripts, Workflows I think the docs should describe what we already use.

whatever you are seeing in the yaml example file is the explanation(more less a comment) that should first be written and adopted in all workflow files, it does not mean its pure yaml syntax, but a guidance to the reader what that worflow is meant for, i guess that's the main intent of the issue. you can correct me if i am wrong

[jona42-ui]

I think the docs should describe what we already use.

Yes partially the current workflows don't enforce explaining the intent of the workflow/script, they simply outright the yaml or python syntax, which is not what the current issue advocates for according to the issue description.

[exploreriii]

Yes, the current workflows are V1, would very much like to raise the level a bit with these documents on what the future should be :)

[exploreriii]

please move line 188 to line 31 ish in your changelog, then great to go! Thank you so much

[github-actions]

Hi, this is MergeConflictBot.
Your pull request cannot be merged because it contains merge conflicts.

Please resolve these conflicts locally and push the changes.

Quick Fix for CHANGELOG.md Conflicts

If your conflict is only in CHANGELOG.md, you can resolve it easily using the GitHub web editor:

1. Click on the "Resolve conflicts" button in the PR
2. Accept both changes (keep both changelog entries)
3. Click "Mark as resolved"
4. Commit the merge

For all other merge conflicts, please read:

• Resolving Merge Conflicts
• Rebasing Guide

Thank you for contributing!

resolved

[coderabbitai]

Actionable comments posted: 5

[github-actions]

Hi, this is WorkflowBot.
Your pull request cannot be merged as it is not passing all our workflow checks.
Please click on each check to review the logs and resolve issues so all checks pass.
To help you:

• DCO signing guide
• Changelog guide
• Merge conflicts guide
• Rebase guide
• Testing guide
• Discord
• Community Calls
  Thank you for contributing!
  From the Hiero Python SDK Team

[exploreriii]

Great work @jona42-ui thank you!