[Advanced]: Add Ruff hook and include in CI pipeline

[exploreriii]

🧠 Advanced Contributors — Prerequisites & Expectations

🐞 Problem Description

We can benefit from a ruff check at the commit level and also in the ci workflows. The reason is if we ever try to fix ruff issues later, there are so many changes and this can be tricky to review. Additionally, we can commit code into the system that is of lower-quality.

Read about
https://docs.astral.sh/ruff/
https://github.com/astral-sh/ruff-action
https://docs.astral.sh/ruff/integrations/

We have some basic configs at pyproject.toml, but these probably need critical thinking to adjust.

Introduce ruff check into the pipeline, you should decide if we should hard fail workflows (can't merge) or just throw a warning.
Consider introducing a ruff hook, so commits are correctly formatted, but consider the trade offs to user experience.

Ensure it:

We would like to:

• be forward looking to align with future hooks/ci
• align with current tooling and pipelines we have
• not break anything, or provide a minimal entry barrier for developers
• Test to see if it keeps good developer experience, what happens if there are existing issues. Do we need documentation? What kind of issues could this cause?

You'll have to study the ruff errors we currently have, decide what kind of standards we should apply.

Caution

This advanced issue requires extensive independent research and testing.

🏁 Concrete Prerequisites

• Proven History: Successfully merged ≥ 5 non-trivial intermediate issues in this repo, including at least 2 relating to github actions.
• Expertise: good architectural understanding of creating high-quality, well tested workflows

⚠️ AI Usage Policy

Using AI to generate code for Advanced issues is strictly discouraged. AI may be used only to help explain file relationships. We require this workflow to work and follow best principles.

⏱️ Timeline & Workflow

• Typical time: ~2 weeks / ~20 hours.
• 🔴 Completing an advanced issue in 1–3 days is a red flag and will likely be rejected.
• Advised: Post your proposed architectural approach as a comment and wait for feedback before writing any code.

🛠️ Implementation Notes

Technical domains involved in this issue:

• CI/CD Integration
  Updates to the GitHub Actions workflow, including triggers (push, pull_request) and job steps for running linting (Ruff) and tests (pytest).
• Code Quality / Linting
  Replacing or supplementing with Ruff for faster linting, rule enforcement, and optional auto-formatting.
• Dependency & Tooling Management
  Installing and managing versions of Ruff and pytest in CI and optionally in local environments.
• Developer Experience (DX) / Pre-commit Hooks
  Using pre-commit to run Ruff locally before commits, ensuring faster feedback and consistent code quality.
• Configuration & Consistency
  Optional Ruff configuration (e.g. pyproject.toml), rule selection, line length, and auto-fix behavior to maintain consistent standards across environments.
• Workflow Optimization
  Streamlining the pipeline by replacing multiple tools (e.g. Flake8 and plugins) with Ruff, reducing CI runtime while maintaining coverage.

🛡️ Quality & Review Standards

The bar for advanced PRs is "safe, maintainable, architecturally sound, and production-ready."

• CI Reliability. Workflow must run consistently on appropriate trigger
• Proper lowest permissions set to limited scope files
• Bandit findings are meaningful and appropriate
• Suitably complements existing tools
• Workflow file is simple, readable, and minimal. Uses stable, well-supported GitHub Actions with hashes.
• Pre-commit hook is appropriate with minimal friction

Notably: Developer architects the solution of how to best apply bandit to the repo

✅ PR Quality Checklist

Before opening your PR, the contributor must confirm:

• I understand the system-wide impact of these changes on affected modules and performance.
• The system design fits with current architectural approaches.
• I have tested my changes extensively against both local and network environments.
• Every line of code is personally understood and explainable and tested

📚 Resources & Support

Sample from github:
https://github.com/actions/starter-workflows/blob/main/code-scanning/bandit.yml

Project References:

• SDK Project Structure
• Transaction Lifecycle
• Hedera Protobufs (v0.72.0-rc.2)

🆘 Stuck?

• Office Hours (Wednesdays, 2pm UTC)
• Discord #hiero-python-sdk

[github-actions]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Configure per-file-ignores to relax docstring and unused-argument rules for tests/examples/tck while maintaining strict standards for source code
• Create a new pr-check-lint.yml workflow following exact existing CI patterns with format as hard-fail and lint as soft-fail initially
• Replace the outdated pylint pre-commit hook with faster ruff format and ruff check hooks that auto-fix issues on commit
• Provide developer documentation on local ruff usage and CI expectations

Design Choices

Design Choice 1: CI Failure Mode for Lint vs Format

Options Considered:

1. Hard-fail for both format and check — blocks all PRs until codebase is fully clean
2. Soft-fail (warn only) for both — provides visibility but no enforcement
3. Hard-fail for format, soft-fail for check — format is auto-fixable and safe; check violations are visible but don't block

Chosen Option: 3

Rationale: Format violations are auto-fixable (developers can run ruff format .) so hard-failing is reasonable, while lint violations need gradual cleanup and should warn without blocking initially.

Design Choice 2: Pre-commit Hook Strategy

Options Considered:

1. Add only ruff format — safe auto-fix, never blocks commits
2. Add only ruff check --fix — auto-fixes where possible, may still block on unfixable violations
3. Add both with format first, then check with --fix — comprehensive but may cause friction

Chosen Option: 3

Rationale: Both hooks with ruff format first (auto-fixes formatting), then ruff check --fix (auto-fixes fixable lint issues). This provides comprehensive coverage while minimizing friction through auto-fixing.

Design Choice 3: Pylint Replacement

Options Considered:

1. Keep both pylint and ruff — redundant coverage, slower hooks
2. Remove pylint, rely on ruff — ruff covers E, F, I, B, SIM rules with much faster execution

Chosen Option: 2

Rationale: Remove pylint from pre-commit. Ruff covers the same error categories and runs significantly faster, aligning with the project's forward-looking tooling goals.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Ruff Configuration Refinement

Configure per-file-ignores in pyproject.toml to relax rules appropriately for test, example, and TCK code, preventing unnecessary noise while maintaining strict standards for production source code.

Task 1: Add Per-File Ignores for Non-Source Directories

Configure ruff to apply relaxed rules to tests, examples, and tck directories where docstrings, unused arguments (fixtures), and other source-code standards are not appropriate.

• Add [tool.ruff.lint.per-file-ignores] section to pyproject.toml
• Ignore D (docstrings) for tests/**, examples/**, tck/** — test files don't require full docstring coverage
• Ignore ARG (unused arguments) for tests/** — pytest fixtures commonly appear unused
• Ignore D100, D104 (module/package docstrings) broadly if needed to reduce noise
• Keep all rules strict for src/hiero_sdk_python/**

Task 2: Review and Confirm Rule Selection

Validate that the existing rule selection is appropriate and adjust if any rules cause excessive noise without providing value.

• Confirm D212 ignore (summary on same line) aligns with Google docstring convention
• Confirm E501 ignore (line length) is appropriate since ruff format handles wrapping
• Confirm B008 ignore (function calls in defaults) is intentional for the SDK's patterns
• Consider adding D1 (missing docstrings) to ignore list temporarily if volume is too high for initial rollout

🤖 Prompt for AI agents

Update the ruff configuration in `pyproject.toml` to add per-file-ignores and
confirm existing rule selections.

- Add a `[tool.ruff.lint.per-file-ignores]` section to `pyproject.toml`
- For `tests/**`: ignore `D` (docstrings) and `ARG` (unused arguments, common
with pytest fixtures)
  - For `examples/**`: ignore `D` (docstrings)
  - For `tck/**`: ignore `D` (docstrings)
- Optionally ignore `D100` and `D104` (module/package docstrings) broadly to
reduce noise
  - Leave all rules strict for `src/hiero_sdk_python/**`
- Review and confirm existing ignores in `pyproject.toml`:
  - `D212` ignore should align with Google docstring convention
  - `E501` ignore is appropriate since ruff format handles line wrapping
  - `B008` ignore is intentional for the SDK's patterns
- Consider temporarily adding `D1` (missing docstrings) to the top-level ignore
list if violation volume is too high for initial rollout

Phase 2: CI Workflow Creation

Create a new GitHub Actions workflow for ruff linting and formatting checks that follows established repository patterns and integrates cleanly with existing PR checks.

Task 1: Create Ruff CI Workflow File

Create .github/workflows/pr-check-lint.yml following the exact patterns from pr-check-test.yml for consistency.

• Create new workflow file in .github/workflows/ directory
• Set name: "PR Lint Check" to align with existing "PR Test Check" naming
• Configure triggers: push to main branch and pull_request events
• Add paths-ignore for docs/**, **/*.md, and other non-Python paths to skip unnecessary runs
• Set permissions: contents: read at workflow level (minimum required)

Task 2: Configure Workflow Job Structure

Set up the lint job with proper security hardening and dependency installation following existing patterns.

• Add single job named lint with runs-on: ubuntu-latest and reasonable timeout-minutes (5-10 is sufficient for linting)
• Include step-security/harden-runner step with same pinned SHA as other workflows
• Include actions/checkout with same pinned SHA
• Include actions/setup-python with pinned SHA, using single Python version (e.g., "3.12") — no matrix needed for linting
• Include astral-sh/setup-uv with same pinned SHA and enable-cache: true
• Add uv sync --all-extras --dev step to install dependencies including ruff

Task 3: Configure Ruff Check and Format Steps

Add the actual ruff execution steps with appropriate failure behavior.

• Add step for uv run ruff format --check --diff . — this should hard-fail (no continue-on-error)
• Add step for uv run ruff check . with continue-on-error: true — allows visibility without blocking PRs initially
• Consider adding --output-format=github flag to ruff check for inline PR annotations
• Add a summary step that reports lint status without failing the workflow for check violations

🤖 Prompt for AI agents

Create a new GitHub Actions workflow file at
`.github/workflows/pr-check-lint.yml` following the exact patterns used in
`pr-check-test.yml`.

- Set `name: "PR Lint Check"`
- Configure triggers for `push` to `main` and `pull_request` events; add
`paths-ignore` for `docs/**`, `**/*.md`, and other non-Python paths
- Set `permissions: contents: read` at the workflow level
- Define a single job named `lint` with:
  - `runs-on: ubuntu-latest`
  - `timeout-minutes` of 5–10
- `step-security/harden-runner` step using the same pinned SHA as other
workflows
  - `actions/checkout` step using the same pinned SHA as other workflows
- `actions/setup-python` step using the same pinned SHA, with a single Python
version (e.g., `"3.12"`) — no matrix needed
- `astral-sh/setup-uv` step using the same pinned SHA, with `enable-cache: true`
  - A dependency installation step running `uv sync --all-extras --dev`
- A hard-fail step running `uv run ruff format --check --diff .` (no
`continue-on-error`)
- A soft-fail step running `uv run ruff check .` with `continue-on-error: true`;
consider adding `--output-format=github` for inline PR annotations
- A summary step that reports lint status without failing the workflow for check
violations

Phase 3: Pre-commit Integration

Update the pre-commit configuration to use ruff for both formatting and linting, replacing the outdated pylint hook with faster, more comprehensive ruff coverage.

Task 1: Add Ruff Hooks to Pre-commit Configuration

Configure ruff hooks in .pre-commit-config.yaml following ruff's official pre-commit integration pattern.

• Add new repo entry for https://github.com/astral-sh/ruff-pre-commit
• Pin to a stable version that aligns with the ruff>=0.14.9,<1 constraint in pyproject.toml
• Add ruff-format hook first — runs ruff format to auto-fix formatting
• Add ruff hook second — runs ruff check --fix to auto-fix linting issues where possible
• Configure both hooks to run on Python file types

Task 2: Remove Pylint Hook

Remove the redundant pylint hook since ruff covers overlapping rules with better performance.

• Remove the pylint-dev/pylint repo entry from .pre-commit-config.yaml
• Ruff already covers pycodestyle (E), pyflakes (F), isort (I), bugbear (B), and simplify (SIM) rules that pylint checks
• This reduces pre-commit execution time significantly

Task 3: Update Pre-commit Hook Versions

Ensure all pre-commit hooks use current, stable versions.

• Review pre-commit/pre-commit-hooks version (currently v4.4.0) and update if newer stable version available
• Review gitleaks/gitleaks version (currently v8.16.3) and update if newer stable version available
• Ensure version consistency across the configuration

🤖 Prompt for AI agents

Update `.pre-commit-config.yaml` to integrate ruff hooks and remove the pylint
hook.

- Add a new repo entry for `https://github.com/astral-sh/ruff-pre-commit`,
pinned to a stable version that satisfies the `ruff>=0.14.9,<1` constraint in
`pyproject.toml`
  - Add the `ruff-format` hook first (runs `ruff format` to auto-fix formatting)
- Add the `ruff` hook second (runs `ruff check --fix` to auto-fix linting issues
where possible)
  - Configure both hooks to run on Python file types
- Remove the `pylint-dev/pylint` repo entry entirely — ruff already covers
pycodestyle (E), pyflakes (F), isort (I), bugbear (B), and simplify (SIM) rules
- Review and update the `pre-commit/pre-commit-hooks` version (currently v4.4.0)
if a newer stable version is available
- Review and update the `gitleaks/gitleaks` version (currently v8.16.3) if a
newer stable version is available
- Ensure version consistency across all hook entries

Phase 4: Documentation and Developer Guidance

Provide clear guidance for developers on using ruff locally and understanding the CI integration.

Task 1: Add Ruff Usage Documentation

Create or update documentation explaining how developers should work with ruff locally.

• Document how to run ruff format . and ruff check . locally before committing
• Document how to run ruff check --fix . to auto-fix violations
• Explain the pre-commit hook behavior and how it auto-fixes on commit
• Add to existing developer documentation (e.g., docs/sdk_developers/ or CONTRIBUTING.md)

Task 2: Document CI Behavior and Expectations

Explain what the CI checks and how developers should respond to failures.

• Document that format check failures require running ruff format . locally
• Document that lint check warnings (initially soft-fail) show areas for improvement
• Explain that lint check will eventually become a hard requirement
• Consider adding troubleshooting for common violations (UP typing upgrades, D docstrings)

🤖 Prompt for AI agents

Create or update developer documentation (e.g., `docs/sdk_developers/` or
`CONTRIBUTING.md`) to cover ruff usage and CI behavior.

- Add a section on local ruff usage:
  - How to run `ruff format .` and `ruff check .` before committing
  - How to run `ruff check --fix .` to auto-fix violations
  - Explanation of the pre-commit hook behavior and how it auto-fixes on commit
- Add a section on CI behavior:
  - Format check failures require running `ruff format .` locally (hard-fail)
  - Lint check warnings are initially soft-fail and show areas for improvement
  - Lint check will eventually become a hard requirement
- Optionally include troubleshooting guidance for common violations such as UP
typing upgrades and D docstrings

Research

The repository is a Python SDK with source code in src/hiero_sdk_python/ (152 files across 16 subpackages), plus tests/, examples/, and tck/ directories. Ruff is already configured in pyproject.toml with rules D, E, F, I, B, UP, SIM, PERF, ARG, RET, RSE but lacks per-file-ignores, causing widespread violations in test/example code. The CI uses a consistent pattern: step-security/harden-runner → actions/checkout → actions/setup-python → astral-sh/setup-uv with pinned SHA hashes, uv sync --all-extras --dev for installation, and uv run for execution. Pre-commit currently uses pylint (v2.17.2) which overlaps significantly with ruff's rule coverage.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Update the ruff configuration in `pyproject.toml` to add per-file-ignores and
confirm existing rule selections.

- Add a `[tool.ruff.lint.per-file-ignores]` section to `pyproject.toml`
- For `tests/**`: ignore `D` (docstrings) and `ARG` (unused arguments, common
with pytest fixtures)
  - For `examples/**`: ignore `D` (docstrings)
  - For `tck/**`: ignore `D` (docstrings)
- Optionally ignore `D100` and `D104` (module/package docstrings) broadly to
reduce noise
  - Leave all rules strict for `src/hiero_sdk_python/**`
- Review and confirm existing ignores in `pyproject.toml`:
  - `D212` ignore should align with Google docstring convention
  - `E501` ignore is appropriate since ruff format handles line wrapping
  - `B008` ignore is intentional for the SDK's patterns
- Consider temporarily adding `D1` (missing docstrings) to the top-level ignore
list if violation volume is too high for initial rollout
===============================================================================

Task: 2

Create a new GitHub Actions workflow file at
`.github/workflows/pr-check-lint.yml` following the exact patterns used in
`pr-check-test.yml`.

- Set `name: "PR Lint Check"`
- Configure triggers for `push` to `main` and `pull_request` events; add
`paths-ignore` for `docs/**`, `**/*.md`, and other non-Python paths
- Set `permissions: contents: read` at the workflow level
- Define a single job named `lint` with:
  - `runs-on: ubuntu-latest`
  - `timeout-minutes` of 5–10
- `step-security/harden-runner` step using the same pinned SHA as other
workflows
  - `actions/checkout` step using the same pinned SHA as other workflows
- `actions/setup-python` step using the same pinned SHA, with a single Python
version (e.g., `"3.12"`) — no matrix needed
- `astral-sh/setup-uv` step using the same pinned SHA, with `enable-cache: true`
  - A dependency installation step running `uv sync --all-extras --dev`
- A hard-fail step running `uv run ruff format --check --diff .` (no
`continue-on-error`)
- A soft-fail step running `uv run ruff check .` with `continue-on-error: true`;
consider adding `--output-format=github` for inline PR annotations
- A summary step that reports lint status without failing the workflow for check
violations
===============================================================================

Task: 3

Update `.pre-commit-config.yaml` to integrate ruff hooks and remove the pylint
hook.

- Add a new repo entry for `https://github.com/astral-sh/ruff-pre-commit`,
pinned to a stable version that satisfies the `ruff>=0.14.9,<1` constraint in
`pyproject.toml`
  - Add the `ruff-format` hook first (runs `ruff format` to auto-fix formatting)
- Add the `ruff` hook second (runs `ruff check --fix` to auto-fix linting issues
where possible)
  - Configure both hooks to run on Python file types
- Remove the `pylint-dev/pylint` repo entry entirely — ruff already covers
pycodestyle (E), pyflakes (F), isort (I), bugbear (B), and simplify (SIM) rules
- Review and update the `pre-commit/pre-commit-hooks` version (currently v4.4.0)
if a newer stable version is available
- Review and update the `gitleaks/gitleaks` version (currently v8.16.3) if a
newer stable version is available
- Ensure version consistency across all hook entries
===============================================================================

Task: 4

Create or update developer documentation (e.g., `docs/sdk_developers/` or
`CONTRIBUTING.md`) to cover ruff usage and CI behavior.

- Add a section on local ruff usage:
  - How to run `ruff format .` and `ruff check .` before committing
  - How to run `ruff check --fix .` to auto-fix violations
  - Explanation of the pre-commit hook behavior and how it auto-fixes on commit
- Add a section on CI behavior:
  - Format check failures require running `ruff format .` locally (hard-fail)
  - Lint check warnings are initially soft-fail and show areas for improvement
  - Lint check will eventually become a hard requirement
- Optionally include troubleshooting guidance for common violations such as UP
typing upgrades and D docstrings

💡 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!