diff --git a/CHANGELOG.md b/CHANGELOG.md index adeabaf06..33bb18f9b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1. ### Docs +- docs: Refactor and organise SDK documentation; delete obsolete directories (`community-calls`, `github`, `workflows`, `maintainers`, `sdk_developers/automations`) and generic guides (`signing.md`, `rebasing.md`, `merge_conflicts.md`, `changelog_entry.md`) now maintained in the upstream `sdk-collaboration-hub`; relocate `team.md` to `docs/team.md`; redirect all affected inbound links in `README.md`, `CONTRIBUTING.md`, and internal developer docs to upstream equivalents (#2101) ### .github - Renamed community call and office hour bots to use the `cron-` prefix (#2068) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dd201a87d..93c042e21 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,10 +38,10 @@ Thank you for your interest in contributing to the Hiero Python SDK! **Detailed Docs:** - [Setup Guide](docs/sdk_developers/setup.md) -- [Signing Guide](docs/sdk_developers/signing.md) -- [Changelog Guide](docs/sdk_developers/changelog_entry.md) -- [Rebasing Guide](docs/sdk_developers/rebasing.md) -- [Merge Conflicts Guide](docs/sdk_developers/merge_conflicts.md) +- [Signing Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/signing.md) +- [Changelog Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/changelog-guide.md) +- [Rebasing Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/rebasing.md) +- [Merge Conflicts Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/merge_conflicts.md) - [Testing Guide](docs/sdk_developers/testing.md) @@ -103,11 +103,11 @@ We welcome blog posts! Whether you're sharing a tutorial, case study, or your ex |-------|----------------| | [Setup](docs/sdk_developers/setup.md) | Fork, clone, install, configure | | [Workflow](docs/sdk_developers/workflow.md) | Branching, committing, PRs | -| [Signing](docs/sdk_developers/signing.md) | GPG + DCO commit signing | -| [Changelog](docs/sdk_developers/changelog_entry.md) | Writing changelog entries | +| [Signing](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/signing.md) | GPG + DCO commit signing | +| [Changelog](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/changelog-guide.md) | Writing changelog entries | | [Checklist](docs/sdk_developers/checklist.md) | Pre-submission checklist | -| [Rebasing](docs/sdk_developers/rebasing.md) | Keeping branch updated | -| [Merge Conflicts](docs/sdk_developers/merge_conflicts.md) | Resolving conflicts | +| [Rebasing](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/rebasing.md) | Keeping branch updated | +| [Merge Conflicts](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/merge_conflicts.md) | Resolving conflicts | | [Types](docs/sdk_developers/types.md) | Python type hints | | [Linting](docs/sdk_developers/linting.md) | Code quality tools | @@ -158,7 +158,7 @@ git checkout your-branch git rebase main -S ``` -**Full guide:** [Rebasing Guide](docs/sdk_developers/rebasing.md) +**Full guide:** [Rebasing Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/rebasing.md) --- diff --git a/README.md b/README.md index 6a89fc4eb..d15d999a4 100644 --- a/README.md +++ b/README.md @@ -68,10 +68,10 @@ print(f"Balance: {balance.hbars} HBAR") - **[Setup Guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/setup.md)** - First-time environment setup - **[Windows Setup Guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/setup_windows.md)** - Step-by-step guide for Windows users - **[Workflow Guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/workflow.md)** - Day-to-day development workflow -- **[Signing Guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/signing.md)** - GPG and DCO commit signing (required) -- **[Changelog Guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/changelog_entry.md)** - How to write changelog entries -- **[Rebasing Guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/rebasing.md)** - Keep your branch up-to-date -- **[Merge Conflicts Guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/merge_conflicts.md)** - Resolve conflicts +- **[Signing Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/signing.md)** - GPG and DCO commit signing (required) +- **[Changelog Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/changelog-guide.md)** - How to write changelog entries +- **[Rebasing Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/rebasing.md)** - Keep your branch up-to-date +- **[Merge Conflicts Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/merge_conflicts.md)** - Resolve conflicts - **[Typing Guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/types.md)** - Python type hints - **[Linting Guide](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_developers/linting.md)** - Code quality tools diff --git a/docs/community-calls/18-02-25.md b/docs/community-calls/18-02-25.md deleted file mode 100644 index 911b68dc9..000000000 --- a/docs/community-calls/18-02-25.md +++ /dev/null @@ -1,89 +0,0 @@ -# Hiero Python SDK – Community Call Notes - -## Objectives -- Align on goals going forward - ---- - -## Topics Discussed -1. **Version Support** -2. **Release Strategy, Committing, and Merging** -3. **README Organization** - ---- - -## Issues Raised - -### Versioning -- **Proposal**: Use `0.1.0` format following `MAJOR.MINOR.PATCH`. -- **Outcome**: Agreed to adopt semantic versioning (0.1.0 is next release). - ---- - -## Release Strategy - -### Proposal -- Release every **2–4 weeks**, ideally on **Wednesday**. -- Merge changes into `main`. -- Deploy from a `/release` branch: - - A short-lived branch created on **Tuesday** (the day before release) for final testing and release notes. -- Maintain a `CHANGELOG` to document changes. - -### Outcome -- Typically aim for **every 2 weeks**, but if there’s not enough to release, it can go up to 4 weeks. - ---- - -## Branching, Committing, and Merging - -### Proposal -- **Branching**: Trunk-based development. - - Example branch names: `feature/update_transaction`, `fix/generate_proto_error`. - - `main` is always stable/production-ready. -- **Committing**: Use conventional commit prefixes such as `feat`, `fix`, `docs`, `chore`, `test`, `refactor`, `style`. - - Meaningful commits are more important than perfect prefixes. - - **Outcome**: - - PR titles should ideally include `feat:` or `fix:`. - - Individual commits can be more descriptive if that’s more natural, but clarity is key. -- **Merging**: - - **Squash & Merge** is preferred. - - Use **GPG key signing** (e.g., `git commit -s -S -m "added docstrings"`). - - **Outcome**: General consensus on using squash, ensuring commits are signed, and writing good commit messages. - ---- - -## README -- The current `README.md` is growing large. -- Suggestion that future examples could become a general doc referencing multiple SDKs, with a link to Hiero specifics. -- For now, we’ll add a specialized `README` in `/examples` to document syntax and transaction types. - -**Outcome**: -- Decision to move the current syntax/transaction-type content from `README.md` into a new `README` under `examples/`. - ---- - -## Questions / Additional Notes - -- Concerns were raised about GPG key setup on macOS requiring extra configuration not documented. - - **Action**: update `README.md` with a GPG setup walkthrough. -- Issues raised installing `uv` and running tests. All resolved, will be documented with steps. -- Differences across various SDKs were noted. Plans to start an **SDK meeting in two weeks** to explore more seamless cross-SDK development. -- Version `0.1.0` to be released 19th of February 2025. -- Deletion of unused / dummy versions. - ---- - -## Summary of Outcomes - -1. **Versioning**: Adopt `0.1.0` for next release; continue using semantic versioning. -2. **Release Cadence**: Aim for every 2 weeks, or extend to 4 weeks if needed. -3. **Branching & Committing**: Trunk-based with feature/fix branches, conventional commit messages (with some flexibility). -4. **Merging**: Prefer squash and GPG signing. -5. **README**: Move large sections (e.g., syntax/transaction details) to a separate doc in `/examples/`. -6. **Action Items**: - - Finalize the `0.1.0` release. - - Document GPG setup steps for macOS users. - - Provide notes on `uv` installation/test fix. - - Schedule a cross-SDK alignment meeting in two weeks. - - Remove dummy versions. - diff --git a/docs/github/04_workflow_documentation.md b/docs/github/04_workflow_documentation.md deleted file mode 100644 index 239137d99..000000000 --- a/docs/github/04_workflow_documentation.md +++ /dev/null @@ -1,435 +0,0 @@ -# Workflow Documentation Guide - -This guide establishes best practices for documenting GitHub workflows and automation scripts in the Hiero Python SDK. Well-documented workflows ensure that contributors, maintainers, and collaborators can quickly understand system behavior without unnecessary deep dives into implementation details. - -## Table of Contents - -- [Overview](#overview) -- [Workflow YAML Documentation](#workflow-yaml-documentation) -- [Script File Documentation](#script-file-documentation) -- [Write Good Docstrings](#write-good-docstrings) -- [Make Exit Reasons Obvious](#make-exit-reasons-obvious) -- [Name Things Clearly](#name-things-clearly) -- [Documentation Checklist](#documentation-checklist) -- [Related Documentation](#related-documentation) - -## Overview - -GitHub workflows consist of two parts: - -1. **Workflow YAML files** (`.github/workflows/*.yml`) - Define triggers and orchestrate execution -2. **Script files** (`.github/scripts/*`) - Contain the actual logic and rules - -Documentation must reflect this separation: - -- **YAML workflows** have minimal comments (1-2 lines) pointing to the script file -- **Script files** contain all detailed documentation: purpose, major rules, logic, assumptions, and edge cases - -This separation ensures readers understand the system architecture without scrolling through implementation details. - ---- - -## Workflow YAML Documentation - -Workflow YAML files orchestrate execution but don't contain business logic. Keep documentation minimal - just a brief comment pointing to the script file. - -### What to Document in YAML Files - -A brief comment (1-2 lines) explaining: -- What the workflow does (briefly) -- Which script file contains the logic - -**Note:** Detailed documentation belongs in the script files, not in YAML. The YAML is just the trigger/orchestration layer. - -### Example: Contributor Self-Assignment Workflow - -This example shows a well-documented GitHub Actions workflow (`.github/workflows/bot-gfi-assign-on-comment.yml`): - -```yaml -# Handles contributor self-assignment via "/assign" comment. -# See .github/scripts/bot-gfi-assign-on-comment.js for validation logic and rules. - -name: GFI Assign on /assign - -on: - issue_comment: - types: - - created - -permissions: - issues: write - contents: read - -jobs: - gfi-assign: - if: github.event.issue.pull_request == null - runs-on: hl-sdk-py-lin-md - - concurrency: - group: gfi-assign-${{ github.event.issue.number }} - cancel-in-progress: false - - steps: - - name: Checkout repository - uses: actions/checkout@v6.0.1 - - - name: Run GFI /assign handler - uses: actions/github-script@v8.0.0 - with: - script: | - const script = require('./.github/scripts/bot-gfi-assign-on-comment.js'); - await script({ github, context }); -``` - -### Example: PR Changelog Validation Workflow - -This example shows a well-documented GitHub Actions workflow (`.github/workflows/pr-check-changelog.yml`): - -```yaml -# Validates that PRs include changelog entries under [Unreleased]. -# See .github/scripts/pr-check-changelog.sh for validation rules. - -name: 'PR Changelog Check' - -on: - pull_request: - types: [opened, reopened, edited, synchronize] - -permissions: - contents: read - -jobs: - changelog-check: - runs-on: hl-sdk-py-lin-md - - steps: - - name: Checkout repository - uses: actions/checkout@v6.0.1 - with: - fetch-depth: 0 - - - name: Run changelog validation - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - chmod +x .github/scripts/pr-check-changelog.sh - bash .github/scripts/pr-check-changelog.sh -``` - ---- - -## Script File Documentation - -Script files (`.github/scripts/*`) contain the actual logic and business rules. Most scripts in the Hiero SDK are written in JavaScript. Documentation here should be comprehensive. - -### What to Document in Script Files - -- **Purpose** - What problem does this script solve? -- **Called By** - Which workflow(s) execute this script? -- **Major Rules** - What are the critical constraints and validation logic? -- **Dependencies** - External packages or APIs used -- **Related Docs** - Links to associated documentation - -### Example: GFI Self-Assignment Script - -This example shows a well-documented script file (`.github/scripts/bot-gfi-assign-on-comment.js`): - -```javascript -// PURPOSE -// ------- -// Handles contributor self-assignment logic when "/assign" is commented. -// Validates prerequisites and enforces assignment rules for Good First Issues. -// -// CALLED BY -// --------- -// Workflow: .github/workflows/bot-gfi-assign-on-comment.yml -// -// MAJOR RULES -// ----------- -// 1. Only allow assignment to Good First Issues -// 2. Never override an existing assignment -// 3. Check user is not on spam list -// 4. Enforce max 3 open assigned issues per user -// 5. Post helpful comment with unassigned GFI link on success -// -// DEPENDENCIES -// ------------ -// - @actions/github for GitHub API access -// - @actions/core for logging -// -// RELATED DOCS -// ------------ -// - Issue Guidelines: docs/maintainers/good_first_issues_guidelines.md -// - Contributor Workflow: docs/sdk_developers/workflow.md - -module.exports = async ({ github, context }) => { - // Implementation... -}; -``` - -### Example: Changelog Validation Script - -This example shows a well-documented bash script (`.github/scripts/pr-check-changelog.sh`): - -```bash -#!/bin/bash -# PURPOSE -# ------- -# Validates that PRs contain proper changelog entries under [Unreleased] -# before allowing merge. -# -# CALLED BY -# --------- -# Workflow: .github/workflows/pr-check-changelog.yml -# -# MAJOR RULES -# ----------- -# 1. New changelog entries must exist in CHANGELOG.md -# 2. Entries must be placed under [Unreleased] section only -# 3. Entries must be under a valid category (Added, Changed, Fixed, etc.) -# 4. Entries placed under released versions will fail the check -# 5. Block merge if entries are missing or improperly placed -# -# DEPENDENCIES -# ------------ -# - git for diff operations -# - grep/awk for text processing -# -# RELATED DOCS -# ------------ -# - Changelog Guide: docs/sdk_developers/changelog_entry.md -# - PR Workflow: docs/sdk_developers/workflow.md - -# Implementation... -``` - ---- - -## Write Good Docstrings - -Docstrings should explain intent, assumptions, side effects, and edge cases. This ensures maintainers understand not just what the code does, but why and when it applies. - -Automation scripts in `.github/scripts/` are written in JavaScript. Here are examples of good documentation: - -### Worse Example: Unclear Intent - -```javascript -/** - * Gets skill level - */ -function getSkillLevel(issueLabels) { - // implementation... -} -``` - -### Better Example: Clear Intent and Assumptions - -```javascript -/** - * Determines the contributor difficulty tier from issue labels. - * - * Assumes exactly one skill label should be present on the issue. - * If multiple skill labels exist, the first match in priority order is returned. - * Returns null if no skill label is found, which triggers maintainer escalation - * notifications. - * - * @param {string[]} issueLabels - List of GitHub label strings on the issue - * @returns {string|null} Skill level identifier (Good First Issue, Beginner, - * Intermediate, Advanced) or null if no skill label found - * - * @sideEffects None. This is a pure function that only reads labels. - * - * @edgeCases - * - Multiple skill labels: Priority order is Good First Issue > Beginner > Intermediate > Advanced - * - No labels: Returns null (expected to trigger escalation) - */ -function determineContributorSkillLevelFromLabels(issueLabels) { - const skillLabels = ['Good First Issue', 'Beginner', 'Intermediate', 'Advanced']; - - for (const skillLabel of skillLabels) { - if (issueLabels.includes(skillLabel)) { - return skillLabel; - } - } - - return null; -} -``` - -### Another Example: Script Function Documentation - -```javascript -/** - * Extracts listed skill prerequisites from the issue body. - * - * Looks for a "## Prerequisites" section and parses the checklist items. - * - * @assumptions - * - Prerequisites section format is consistent with issue templates - * - Each prerequisite is a checklist item (- [ ] or - [x]) - * - Unknown prerequisites are skipped with a warning log - * - * @param {string} issueBody - The markdown text of the GitHub issue - * @returns {string[]} List of prerequisite identifiers found in the issue - * - * @sideEffects - * - Logs warnings for unrecognized prerequisites via console.warn - * - Does NOT validate if prerequisites are met - * - * @edgeCases - * - Missing "## Prerequisites" section returns empty array - * - Malformed lines in prerequisites are skipped silently - * - Duplicate prerequisites are preserved as-is - */ -function extractIssuePrerequisites(issueBody) { - // implementation... -} -``` - ---- - -## Make Exit Reasons Obvious - -When code exits early or returns a specific state, the reason should be immediately clear. Use clear comments to explain why the function returns or terminates. - -### Worse Example: Unclear Exit Condition - -```javascript -if (issue.assignees.length > 0) { - return; -} -``` - -### Better Example: Clear Exit Reason - -```javascript -/* - * Safety gate: never override an existing assignment. - * If someone is already assigned, this workflow must not change it. - */ -if (issue.assignees.length > 0) { - await github.rest.issues.createComment({ - owner: context.repo.owner, - repo: context.repo.repo, - issue_number: issue.number, - body: `Cannot self-assign: issue is already assigned to @${issue.assignees[0].login}` - }); - return; -} -``` - -### Another Example: Clear Exit Conditions - -```javascript -/** - * Validate that a contributor can be assigned to this issue. - */ -async function validateAssignmentPrerequisites(contributorId, issue, github) { - /* Exit condition 1: Check contributor exists and is active */ - const contributor = await getContributor(contributorId, github); - if (!contributor || !contributor.is_active) { - console.warn(`Contributor ${contributorId} not found or inactive`); - return false; - } - - /* Exit condition 2: Verify issue has required skill labels */ - const skillLabels = extractSkillLabels(issue); - if (skillLabels.length === 0) { - console.error(`Issue ${issue.number} missing skill level label`); - return false; - } - - /* Exit condition 3: Check contributor skill matches issue requirement */ - const requiredSkill = skillLabels[0]; - if (!contributorHasSkill(contributorId, requiredSkill)) { - console.info(`Contributor ${contributorId} lacks skill: ${requiredSkill}`); - return false; - } - - return true; -} -``` - ---- - -## Name Things Clearly - -Use descriptive names that reveal intent. Function names should be action-oriented and specific. - -### Worse Examples: Vague/Generic Names - -```javascript -makeMsg2() // What kind of message? Why "2"? -handle() // Too generic -process() // Too generic -check() // Check what? -doTest() // Do what test? -``` - -### Better Examples: Clear, Specific Names - -```javascript -buildPrerequisiteNotMetComment() // Creates a specific comment type -validateSkillLevelLabel() // What it validates -notifyMaintainersOfEscalation() // What it notifies and why -extractSkillLevelFromLabels() // What it extracts and from where -verifyContributorHasRequiredSkill() // Specific check being performed -transitionIssueToReadyState() // Specific state transition -``` - -### Examples - -```javascript -// Better: Clear, Action-Oriented Names -async function fetchContributorSkillLevelFromDatabase(contributorId) { - // Retrieve a contributor's verified skill tier -} - -function validateIssueMeetsReadinessCriteria(issue) { - // Returns { isValid: boolean, reason: string } -} - -async function transitionIssueLabelsOnAssignment(issue, oldSkillLevel, newSkillLevel, github) { - // Remove old skill label and apply new one -} -``` - ---- - -## Documentation Checklist - -### For Workflow YAML Files (`.github/workflows/*.yml`) - -- Brief comment (1-2 lines) explaining what the workflow does -- Comment points to the script file that contains the logic -- Does NOT include detailed documentation like PURPOSE, TRIGGER, MAJOR RULES, or RELATED DOCS -- All detailed documentation belongs in the script file - -### For Script Files (`.github/scripts/*`) - -- Header block includes PURPOSE, CALLED BY, MAJOR RULES, DEPENDENCIES, and RELATED DOCS -- Each function has a docstring explaining intent, assumptions, side effects, and edge cases -- Exit conditions are clearly documented with comments explaining why the function returns early -- Function names are descriptive and action-oriented (avoid generic names like `make`, `do`, `process`, `handle`) -- Variable names reveal their purpose and content type -- Complex logic is explained with inline comments for maintainability -- Examples of expected behavior are provided for non-obvious logic - ---- - -## Related Documentation - -- [Contributor Workflow](../sdk_developers/workflow.md) -- [Issue Guidelines](../maintainers/difficulty_overview_guidelines.md) -- [Code Signing and Commits](../sdk_developers/signing.md) - ---- - -Great workflow documentation follows a simple principle: separate orchestration from logic. - -- **Workflow YAML files** document triggers and script references -- **Script files** document major rules and implementation details - -This separation ensures readers understand the system architecture without scrolling through implementation details. - -By following these guidelines, you ensure that your workflows and scripts are accessible, maintainable, and self-documenting. diff --git a/docs/maintainers/GFI/GFI-Frequency.md b/docs/maintainers/GFI/GFI-Frequency.md deleted file mode 100644 index 948542206..000000000 --- a/docs/maintainers/GFI/GFI-Frequency.md +++ /dev/null @@ -1,79 +0,0 @@ -# Good First Issue (GFI) Frequency Guidelines - -## Purpose - -This document defines **how frequently Good First Issues (GFIs)** should be created and maintained for an SDK. - -Clear expectations around GFI frequency help: -- Maintain a healthy contributor pipeline -- Prevent contributor overload or abandonment -- Align GFI availability with maintainer capacity and review bandwidth - -These guidelines are **SDK-specific** and may differ across SDKs depending on team size, activity, and release cadence. - ---- - -## What Is GFI Frequency? - -**GFI frequency** refers to the number of open, actively maintained Good First Issues an SDK aims to support over time. - -This is not a hard requirement, but a **maintainer-defined target** that helps ensure: -- Issues labeled as GFI receive timely responses -- Contributors are not left waiting without feedback -- Maintainers do not overcommit beyond their review capacity - ---- - -## Recommended Frequency Models - -Maintainers may choose one of the following models, or define a custom approach that fits their SDK. - -### 1. Fixed Cadence - -A predictable schedule for creating or refreshing GFIs. - -**Examples:** -- One GFI per month -- One GFI every two weeks -- Two GFIs per week - -This model works well for SDKs with: -- Stable maintainer availability -- Regular contributor interest -- Predictable release cycles - ---- - -### 2. Capacity-Based (Burn Rate) - -GFIs are created based on **maintainer capacity**, not time. - -**Examples:** -- Maintain 1–3 open GFIs at any given time -- Only open a new GFI when an existing one is closed or inactive -- Limit GFIs to what can be reviewed within a defined SLA (e.g., 5 business days) - -This model works well for: -- Small maintainer teams -- Periods of high operational load -- SDKs with fluctuating contributor demand - ---- - -### 3. Hybrid Model - -A combination of cadence and capacity. - -**Examples:** -- One GFI per month, up to a maximum of 3 open GFIs -- Weekly GFI creation, paused when review backlog exceeds a threshold - ---- - -## SDK-Specific Declaration - -Each SDK is encouraged to **explicitly declare its GFI frequency policy**, for example: - -```text -This SDK aims to maintain up to two active Good First Issues at any given time, -subject to maintainer availability. diff --git a/docs/maintainers/GFI/GFI-Management.md b/docs/maintainers/GFI/GFI-Management.md deleted file mode 100644 index 82807419f..000000000 --- a/docs/maintainers/GFI/GFI-Management.md +++ /dev/null @@ -1,176 +0,0 @@ -# Good First Issue (GFI) Management Guidelines - -## Purpose - -This document describes **how Good First Issues (GFIs)** should be managed once they are created. - -Clear management practices help: -- Ensure GFIs remain welcoming and actionable -- Provide consistent contributor experiences -- Balance maintainer workload with community engagement - -These guidelines focus on **maintainer responsibilities and discretion** and are intended to be applied at the **SDK level**. - ---- - -## What Is GFI Management? - -**GFI management** refers to the ongoing actions maintainers take to ensure that: -- Issues labeled as `good first issue` remain suitable for new contributors -- Contributors receive timely guidance and feedback -- GFIs do not become stale, abandoned, or misleading - -Management is not micromanagement; it is **lightweight stewardship**. - ---- - -## GFI Lifecycle Overview - -A Good First Issue typically moves through the following stages: - -1. Identified as a potential GFI (GFIC — Good First Issue Candidate) -2. Reviewed and labeled as a GFI -3. Assigned or claimed by a contributor -4. Actively supported through contribution -5. Completed, relabeled, or closed - -Not all GFIs must follow this exact flow, but clarity around expectations helps contributors succeed. - ---- - -## Labeling and Promotion (GFIC → GFI) - -Maintainers may use an intermediate **Good First Issue Candidate (GFIC)** state. - -### Recommended Practices - -- Use a `good first issue candidate` (or similar) label to flag potential GFIs -- Promote an issue from GFIC → GFI once: - - Scope and acceptance criteria are clear - - The issue meets `GFI-guidelines.md` - - Maintainer capacity exists to support it - -Maintainers are not required to promote every GFIC to a GFI. - ---- - -## Assignment and Claiming - -Maintainers may choose how contributors engage with GFIs. - -### Common Approaches - -- Allow contributors to self-assign -- Assign first-time contributors upon request -- Limit the number of simultaneous GFI assignments per contributor - -### Recommended Guidance - -- Prefer assigning **one contributor per GFI** -- Avoid long-term assignment without activity -- Reclaim or unassign issues after prolonged inactivity, with a clear comment - -This ensures fair access and avoids stalled issues. - ---- - -## Mentorship and Support - -Mentorship is encouraged but **not mandatory**. - -### Examples of Supportive Management - -- Answering clarification questions -- Pointing contributors to relevant files or examples -- Clarifying acceptance criteria -- Suggesting incremental approaches - -### What Is *Not* Expected - -- Writing the solution for the contributor -- Providing extensive code reviews beyond GFI scope -- Guaranteeing real-time or synchronous support - -Light guidance is often sufficient for a successful first contribution. - ---- - -## Review Expectations (“Soft Review”) - -Maintainers may choose to apply a **lighter review standard** for GFIs. - -### Soft Review May Include - -- Prioritizing clarity and correctness over optimization -- Offering constructive, educational feedback -- Allowing minor follow-up improvements after merge - -### Still Required - -- Correctness -- Tests where applicable -- Compliance with project standards - -GFIs should be welcoming, not lower-quality. - ---- - -## Maintainer Discretion and Control - -Maintainers retain full control over: - -- Labeling or removing the `good first issue` label -- Assignment decisions -- Pausing or closing GFIs -- Adjusting management practices over time - -Discretion allows maintainers to adapt to workload, contributor behavior, and project priorities. - ---- - -## Transparency and Community Engagement - -Maintainers are encouraged to: -- Leave brief comments when relabeling or closing GFIs -- Explain pauses or changes in availability -- Encourage contributors to ask questions - -Transparency builds trust and helps the community understand expectations. - ---- - -## Updating GFI Management Practices - -This document is intended to be **easy to update**. - -Maintainers may: -- Adjust management practices at any time -- Experiment with different levels of mentorship or review -- Align management with `GFI-frequency.md` and maintainer capacity - -Updates should be treated as **process guidance**, not rigid policy. - ---- - -## Relationship to Other GFI Documents - -This document complements: -- `good_first_issues_guidelines` — what qualifies as a GFI (docs/maintainers/good_first_issues_guidelines.md) -- `GFI-frequency.md` — how many GFIs to support -- Issue templates and labeling conventions - -Together, these documents provide a complete view of: -- GFI definition -- GFI availability -- GFI stewardship - ---- - -## Summary - -Effective GFI management is: -- Supportive -- Sustainable -- Transparent - -A well-managed Good First Issue benefits contributors, maintainers, and the SDK as a whole. diff --git a/docs/maintainers/advanced_issue_guidelines.md b/docs/maintainers/advanced_issue_guidelines.md deleted file mode 100644 index cb18a042b..000000000 --- a/docs/maintainers/advanced_issue_guidelines.md +++ /dev/null @@ -1,203 +0,0 @@ -# Advanced Issue Guidelines — Hiero Python SDK - -## How to Use This Document - -This guide is here to support maintainers and issue creators who use the **Advanced** label -in the Hiero Python SDK repository. - -It offers shared language and examples to help: - -**Issue creators:** -- Describe larger, more complex tasks clearly -- Set expectations around scope, impact, and collaboration -- Provide helpful context for experienced contributors - -**Maintainers:** -- Apply the Advanced label consistently -- Keep issue difficulty labels clear and useful - -This isn’t a rulebook, and it’s not meant to limit what kinds of contributions are welcome. -All contributions — from small fixes to major improvements — are valuable to the Hiero project. - -The **Advanced** label simply highlights work that involves deeper design, broader impact, -and long-term ownership. - ---- - -## Purpose - -Advanced Issues represent **high-impact, high-responsibility work**. - -They’re a great fit for contributors who: - -- Have deep familiarity with the Python SDK -- Enjoy designing solutions and evaluating trade-offs -- Are comfortable thinking about long-term impact - -These issues often involve shaping how the SDK evolves over time. - ---- - -## What to Expect - -Advanced Issues are designed for contributors who: - -- Have strong Python SDK and domain knowledge -- Understand performance, concurrency, and API stability considerations -- Feel comfortable proposing and discussing designs -- Are open to conversations about breaking changes and long-term direction - -These issues usually involve more discussion, iteration, and collaboration than earlier issue levels. - ---- - -## How Advanced Issues Usually Feel - -Advanced Issues often: - -- Are design-heavy -- Affect multiple parts of the SDK -- Have long-term maintenance impact -- Involve discussion, iteration, and review - -They’re a great fit for contributors who enjoy tackling complex problems and shaping the future of the project. - ---- - -## Common Types of Advanced Work - -Here are some examples of tasks that often fit well at this level: - -### Core SDK Changes -- Significant behavior changes with clear motivation -- Refactors spanning multiple related subsystems -- Improvements to core execution paths or abstractions -- Bug fixes that require investigation across multiple layers - -### Architecture & Design -- Introducing new abstractions or subsystems -- Improving extensibility or testability through redesign -- Decoupling tightly coupled components -- Addressing systemic architectural issues - -### Interfaces & Contracts -- Evolving public or internal APIs with clear rationale -- Formalizing or refining existing contracts -- Improving type consistency across large areas of the codebase -- Introducing shared types or protocols - -### Documentation & Guidance -- Writing or updating architectural documentation -- Explaining non-obvious design decisions -- Adding migration notes or deprecation guidance -- Aligning docs with new behavior or APIs - -### Examples & Developer Experience -- Designing new examples for advanced features -- Updating examples to reflect new APIs or workflows -- Improving clarity around advanced usage patterns - -### Testing & Validation -- Designing new test strategies -- Adding comprehensive coverage for new abstractions -- Refactoring test architecture to support new designs -- Introducing regression tests for complex scenarios - ---- - -## What Advanced Issues Are *Not* - -Advanced Issues are not just “bigger versions” of other issue types. - -If a task: - -- Can be completed by following existing patterns -- Is mostly mechanical or scripted -- Has very limited impact or risk - -…it may be a better fit for **Beginner** or **Intermediate** labels. - -Advanced Issues usually involve: - -- Design choices -- Trade-offs -- Broader context -- Long-term considerations - ---- - -## Typical Scope & Time - -Advanced Issues are usually: - -- ⏱ **Estimated time:** 3+ days -- 📄 **Scope:** Multiple modules or repository-wide -- 🧠 **Challenge level:** Design, iteration, and long-term ownership - -They often evolve through discussion and may require multiple review cycles. - ---- - -## Example: A Well-Formed Advanced Issue - -### Implement HIP-1261 fee estimate query support in the Python SDK - -The Hiero Python SDK doesn’t currently support fee estimate queries as defined in -HIP-1261. This makes it harder for developers to programmatically estimate -transaction fees before execution. - -This issue focuses on **designing and implementing full SDK support** for HIP-1261, including: - -- Public APIs -- Internal request/response handling -- Tests and examples - -The implementation should align with the HIP specification and stay consistent -with patterns used across other SDKs. - -**Reference design document:** -https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/proposals/hips/hip-1261.md - -### Suggested Steps - -1. Review HIP-1261 to understand the intended behavior and constraints -2. Design the Python SDK API surface for fee estimate queries -3. Implement the feature across the SDK, including: - - Public-facing query or transaction classes - - Internal request/response handling - - Validation and error handling -4. Add unit and integration tests -5. Provide at least one usage example - ---- - -## Support & Collaboration - -Advanced Issues are supported through: - -- Design discussions in issues and PRs -- Maintainer and community feedback -- Iterative review cycles - -Support focuses on: - -- Exploring design options -- Evaluating trade-offs -- Ensuring long-term maintainability - -The goal is to build strong, well-considered solutions together. - ---- - -## Maintainer Guidance - -An issue is often a good fit for the **Advanced** label when it: - -- Involves system-level thinking -- Has long-term impact on the SDK -- Benefits from experienced review and iteration - ---- - -Advanced Issues are about shaping the future of the project — -through thoughtful design, collaboration, and long-term vision. diff --git a/docs/maintainers/beginner_issues_guidelines.md b/docs/maintainers/beginner_issues_guidelines.md deleted file mode 100644 index 50203abb5..000000000 --- a/docs/maintainers/beginner_issues_guidelines.md +++ /dev/null @@ -1,165 +0,0 @@ -# Beginner Issue Guidelines — Hiero Python SDK - -## How to Use This Document - -This guide supports maintainers and issue creators who use the **Beginner** label -in the Hiero Python SDK repository. - -It helps: - -**Issue creators:** -- Describe approachable, confidence-building tasks -- Set expectations without over-prescribing solutions -- Provide helpful context for newer contributors - -**Maintainers:** -- Apply the Beginner label consistently -- Keep issue difficulty levels clear and welcoming - -This isn’t a rulebook, and it’s not meant to limit what kinds of contributions are welcome. -All contributions — from small fixes to larger improvements — are valuable to the Hiero project. - -The **Beginner** label highlights work that supports learning, exploration, and growing confidence. - ---- - -## Purpose - -Beginner Issues represent the **next step after Good First Issues**. - -They’re a great fit for contributors who: - -- Are comfortable with the basic contribution workflow -- Want to explore the codebase a little more -- Are ready to take on slightly more independent work - -These issues help contributors grow their confidence in: - -- Reading and understanding existing code -- Making small, thoughtful changes -- Asking good questions and learning by doing - ---- - -## What to Expect - -Beginner Issues are designed for contributors who: - -- Have basic Python experience -- Are familiar with Git and the SDK workflow -- Can navigate a few files in the repository -- Are open to learning how things work under the hood - -These issues usually involve more exploration than Good First Issues, -but still stay focused, approachable, and well-scoped. - ---- - -## How Beginner Issues Usually Feel - -Beginner Issues often: - -- Involve a small number of files -- Require reading and understanding existing behavior -- Leave room for small decisions and learning -- Stay focused on a clear, specific goal - -They’re a great fit for contributors who want to grow their skills without feeling overwhelmed. - ---- - -## Common Types of Beginner Work - -Here are examples of tasks that often fit well at this level: - -### Core SDK Changes -- Improving `__str__` or `__repr__` methods -- Small, localized improvements to utility functions -- Minor behavior tweaks with clear intent -- Changes that require understanding how existing code behaves - -### Typing & Code Quality -- Adding missing type hints in simple functions -- Fixing incorrect type annotations -- Improving consistency within a file - -### Documentation -- Writing or expanding docs for narrow, well-defined areas -- Improving clarity in existing documentation -- Adding helpful explanations to examples - -### Examples -- Creating simple examples based on existing ones -- Adding missing steps to demonstrate functionality -- Improving readability or output clarity -- Making examples more instructional - -### Tests -- Extending existing tests with additional assertions -- Covering specific edge cases -- Improving test naming and clarity - ---- - -## Usually Not Good Fits - -- Purely mechanical tasks -- Large architectural refactors -- Cross-cutting changes across many subsystems -- Work requiring deep protocol or DLT expertise -- Designing new testing frameworks - -These tasks may be a better fit for **Good First Issue**, **Intermediate**, or **Advanced** labels. - ---- - -## Typical Scope & Time - -Beginner Issues are usually: - -- ⏱ **Estimated time:** A few hours to a day -- 📄 **Scope:** One or a few related files -- 🧠 **Challenge level:** Exploration, learning, and light decision-making - -They’re designed to be achievable in a single pull request. - ---- - -## Support & Collaboration - -Beginner Issues are supported through: - -- Issue and PR discussions -- Maintainer and community feedback -- Friendly guidance and clarification - -Support focuses on: - -- Helping contributors understand the code -- Clarifying expectations -- Making the learning process enjoyable - -The goal is to build confidence while keeping the experience positive and encouraging. - ---- - -## Maintainer Guidance - -An issue is often a good fit for the **Beginner** label when it: - -- Builds naturally on Good First Issues -- Requires light investigation or interpretation -- Has a clear goal without being fully scripted -- Encourages learning and questions - -An issue may be better suited for another label if it: - -- Is purely mechanical -- Requires deep domain expertise -- Spans many unrelated parts of the codebase -- Involves architectural or design-level decisions - ---- - -Beginner Issues are about growing skills — -through curiosity, exploration, and thoughtful contributions. diff --git a/docs/maintainers/difficulty_overview_guidelines.md b/docs/maintainers/difficulty_overview_guidelines.md deleted file mode 100644 index e72e6d7d0..000000000 --- a/docs/maintainers/difficulty_overview_guidelines.md +++ /dev/null @@ -1,139 +0,0 @@ -# Issue Difficulty Overview — Hiero Python SDK - -## How to Use This Document - -This page gives a simple overview of how issue labels are used in the -Hiero **Python SDK** repository. - -It’s here to help: - -**Contributors:** -- Find issues that match their experience level -- Understand what to expect from different types of tasks -- Grow their skills over time - -**Maintainers:** -- Apply labels consistently -- Set clear expectations for issue scope and readiness -- Make the contribution experience smoother for everyone - -This isn’t a rulebook, and it’s not about limiting who can contribute. -It’s about helping people find the right starting point and build confidence along the way. - ---- - -## Why We Use Issue Labels - -The labeling system is designed to: - -- Help contributors choose tasks that feel comfortable and achievable -- Make expectations around scope and independence clearer -- Support a natural progression from first PR to deeper ownership -- Create a positive, trust-building contribution experience - -Everyone is welcome to contribute — labels simply help guide the journey. - ---- - -## Readiness & Difficulty Labels - -Each issue typically has: - -- **One difficulty label** - (Good First Issue, Beginner, Intermediate, or Advanced) -- An optional **readiness label** - (Good First Issue: Candidate) - -Together, these give contributors a sense of both: - -- How complex the task is -- How ready it is for first-time contributors - ---- - -### Readiness Label (Optional, Temporary) - -| Label | What It Means | -|------|----------------| -| **Good First Issue: Candidate** | This issue might become a Good First Issue, but could use a little more clarity or polish first | - -The candidate label is a friendly “almost ready” marker. -It gives maintainers time to refine the issue before promoting it. - ---- - -### Difficulty Progression - -| Level | Focus | What to Expect | -|------|--------|----------------| -| **Good First Issue** | Getting started | Clear, step-by-step tasks | -| **Beginner** | Building confidence | Small, guided improvements | -| **Intermediate** | Growing ownership | Flexible, multi-file changes | -| **Advanced** | Shaping the system | Design-focused, high-impact work | - -Each level reflects a gradual increase in: - -- Independence -- Context -- Technical ownership - ---- - -## How the Labels Work Together - -- **Good First Issue: Candidate** - → Signals potential, not final readiness - -- **Good First Issue** - → Fully guided, step-by-step, and friendly for first-time contributors - -- **Beginner / Intermediate / Advanced** - → Indicate increasing levels of exploration, judgment, and ownership - -The goal is to make it easy for contributors to find issues that match their comfort level and grow from there. - ---- - -## Choosing the Right Label - -In general: - -- Each issue has **one main difficulty label** -- The candidate label is optional and temporary -- If a task needs more clarity, it can stay in the candidate stage -- If an issue feels more complex than expected, it’s okay to choose a higher difficulty level - -Exploratory or open-ended issues usually work best with -**Intermediate** or **Advanced** labels, where discussion and design are part of the process. - ---- - -## From Candidate to Good First Issue - -The candidate label exists to help maintainers prepare issues for new contributors. - -Once an issue feels: - -- Clear -- Well-scoped -- Easy to follow -- And friendly for first-time contributors - -It can be promoted to a **Good First Issue**. - -Taking a little extra time here helps create a smoother, more welcoming experience. - ---- - -## The Big Picture - -Issue labels exist to: - -- Support contributors -- Set clear expectations -- Encourage steady skill growth -- Build confidence over time - -**Accuracy matters more than volume**, because a great first experience is worth more than a long list of confusing issues. - -Everyone is welcome — these labels just help people find the best place to begin. diff --git a/docs/maintainers/good_first_issue_candidate_guidelines.md b/docs/maintainers/good_first_issue_candidate_guidelines.md deleted file mode 100644 index ebc4e9bb8..000000000 --- a/docs/maintainers/good_first_issue_candidate_guidelines.md +++ /dev/null @@ -1,171 +0,0 @@ -# Good First Issue — Candidate Guidelines -**Hiero Python SDK** - -## How to Use This Document - -This guide is intended to support **maintainers and issue creators** who use the -**`good first issue: candidate`** label. - -It provides shared language and guidance to help: - -**Issue creators:** -- Flag issues that *might* be a good starting point for new contributors -- Identify where additional clarity or detail is needed -- Prepare issues for promotion to a full Good First Issue - -**Maintainers:** -- Protect the quality and trustworthiness of Good First Issues -- Give issues time to be refined before promotion - -This document is not a strict rulebook, and it is not meant to limit what kinds of contributions are welcome. -All contributions are valuable to the Hiero project. - -The **candidate** label simply helps ensure that Good First Issues offer a smooth and confidence-building first experience. - ---- - -## What the Candidate Label Is For - -The **`good first issue: candidate`** label is used to mark issues that *appear* suitable for first-time contributors, but may still need a bit more clarity, polish, or confirmation before being promoted to a full **Good First Issue (GFI)**. - -It provides a safe “holding state” where maintainers can refine the issue without prematurely advertising it as ready for new contributors. - -The candidate label is **not** a softer or lower-quality GFI — it is a **preparation stage**. - ---- - -## Why This Label Exists - -Some issues look small and approachable, but may still be missing: - -- Clear step-by-step instructions -- Explicit file paths or locations -- Well-defined acceptance criteria -- Confidence about difficulty or scope - -The candidate label helps signal: - -> “This issue is close — it just needs a little more detail before it’s ready.” - -This protects the credibility of the Good First Issue label and helps ensure a positive experience for new contributors. - ---- - -## When to Use `good first issue: candidate` - -Apply the **candidate** label when an issue appears suitable for a Good First Issue, but is **not fully ready yet**. - -### ✅ Potentially a Good First Issue - -The issue likely qualifies because: - -- The change appears small, localized, and low risk -- The task fits within allowed GFI categories (documentation, examples, typing, or small mechanical edits) -- The issue does not require exploration, investigation, or design decisions - -Suitability can be evaluated using the - -[**Good First Issue Guidelines**](./good_first_issues_guidelines.md) - ---- - -### ✅ Needs Refinement Before Promotion - -One or more of the following is still missing: - -- Explicit step-by-step implementation instructions -- Clear and objective acceptance criteria - -At this stage, the issue may include partial notes, rough ideas, or reminders for maintainers to clarify later — and that’s okay. - ---- - -### ✅ Difficulty Is Uncertain - -Use the candidate label when: - -- The issue *seems* easy, but you are not fully confident -- The scope or effort needs maintainer confirmation - -The candidate stage allows time to confirm that the issue is truly appropriate for first-time contributors. - -If an issue turns out to be more complex, it is usually better labeled as a **Beginner Issue** instead of a GFI. - ---- - -## What a Candidate Is NOT - -The candidate label is intended for issues that are potential Good First Issues but may need additional detail or scoping to be fully beginner-friendly. - -### ❌ Not for Issues Requiring Decisions - -If a contributor must decide: - -- *What* should change -- *How* something should behave -- *What* is correct or expected - -Then the issue is **not** a candidate. - ---- - -### ❌ Not for Core or Behavioral Changes - -Do not use the candidate label for issues involving: - -- SDK or protocol behavior -- Public APIs or contracts -- `to_proto` / `from_proto` logic -- Serialization, deserialization, or networking - ---- - -### ❌ Not for Exploratory or Blocked Work - -Avoid using the candidate label for: - -- Investigations or debugging tasks -- Issues blocked on other PRs or decisions -- Work requiring domain or protocol knowledge - -> ⚠️ If an issue clearly does *not* meet Good First Issue criteria, -> do **not** label it as a candidate. -> The candidate label is for issues that *might* qualify after refinement — not for issues that never will. - ---- - -## Promoting a Candidate to Good First Issue - -An issue should only be promoted to a full **Good First Issue** once it is clearly ready for first-time contributors. - -### ✅ Readiness Checklist - -Before promoting an issue to Good First Issue, consider checking whether: - -- [ ] The problem is clearly described and easy to understand for someone new to the project. -- [ ] The solution is **explicitly specified** -- [ ] The change is small, localized, and low risk -- [ ] The issue touches a single file or clearly defined location -- [ ] Acceptance criteria are objective and complete -- [ ] No interpretation, investigation, or initiative is required - ---- - -### 🔁 Promotion Process - -1. Review the issue against the [**Good First Issue Guidelines**](./good_first_issues_guidelines.md) -2. Add missing details, steps, and acceptance criteria -3. Remove the `good first issue: candidate` label -4. Apply the **Good First Issue** label - -There is no rush — taking the time to refine an issue is part of creating a welcoming and supportive community. - ---- - -## The Big Picture - -The **Good First Issue — Candidate** label helps make the Hiero Python SDK accessible and friendly for everyone — especially new contributors. - -All contributions are welcome. -This label simply helps highlight the best place to begin. - diff --git a/docs/maintainers/good_first_issues_guidelines.md b/docs/maintainers/good_first_issues_guidelines.md deleted file mode 100644 index 8ea15af7c..000000000 --- a/docs/maintainers/good_first_issues_guidelines.md +++ /dev/null @@ -1,209 +0,0 @@ -# Good First Issue Guidelines — Hiero Python SDK - -## How to Use This Document - -This guide is intended to help **maintainers and issue creators** use the **Good First Issue (GFI)** label consistently and effectively in the Hiero Python SDK. - -It provides shared language, examples, and guidance to help: - -**Issue creators:** -- Feel confident proposing a Good First Issue -- Understand what makes an issue approachable for new contributors -- Decide when a task might be better suited for another issue label - -**Maintainers:** -- Apply the Good First Issue label consistently -- Keep issue difficulty labels clear, predictable, and helpful - -This document is not meant to limit contributions or discourage initiative. -All contributions — large or small — are valuable to the Hiero project. - -The Good First Issue label simply highlights tasks that are especially friendly for **first-time contributors**. - ---- - -## Purpose - -Good First Issues (GFIs) are designed to provide a **welcoming, confidence-building first contribution experience** for new community members. - -They help contributors: - -- Get set up successfully -- Navigate the repository -- Open their first pull request - -For many contributors, this is their **first interaction with open source** or with the Hiero SDK codebase. -Good First Issues are designed to make that experience smoother by offering: - -- Clear, well-scoped tasks -- **Explicit or step-by-step implementation instructions** -- Predictable and easy-to-verify outcomes - -The emphasis is on learning the workflow — **not** on researching behavior, making design decisions, or filling in missing context. - ---- - -## What to Expect - -Good First Issues are intended for contributors who: - -- Have basic Python knowledge -- Are familiar with Git and GitHub -- Are new to the Hiero SDK -- Do not yet understand the SDK’s architecture or internal design - -Ideally, everything needed to complete the task is included directly in the issue description. - -If a task requires investigation, interpretation, or design judgment, it is likely a better fit for another issue label — and that is perfectly okay. - ---- - -## What Makes a Good First Issue - -A Good First Issue works best when it is: - -- Clearly defined -- **Fully specified or scripted with explicit instructions** -- Small in scope (often a single file or location) -- Easy to review and verify - -The solution path should feel clear and direct, allowing contributors to focus on learning the contribution process rather than figuring out what needs to be done. - -### Helpful Rule of Thumb - -> If a contributor must **decide what to do or how something should work**, -> it is **not** a Good First Issue. - ---- - -## Typical Scope & Time - -Good First Issues are intentionally small and focused: - -- ⏱ **Estimated time:** ~1–4 hours (including setup) -- 📄 **Scope:** One file or a clearly defined section -- 🧠 **Type:** Straightforward, mechanical, low-risk changes - -Most of the effort should go into getting comfortable with the workflow — not solving complex technical problems. - ---- - -## Common Good First Issue Examples - -The following are good fits for Good First Issues **when the solution is explicitly described**. - -### Small, Focused Source Changes - -> ⚠️ In most cases, changes to `src` functionality are **not** Good First Issues. -> This category applies only when the change is **purely mechanical and fully specified**. - -### Suitable for Good First Issues (rare, explicit cases only): -- Very small, explicitly described edits to existing code -- Changes that do not require understanding how the code is used elsewhere - -### Not Suitable for Good First Issues -- Any change that requires deciding *how* something should behave -- Any change that affects public behavior or SDK contracts - ---- - -### Typing Improvements - -Typing-related Good First Issues must be **fully specified and mechanical**. - -### Suitable for Good First Issues -- Adding missing return type hints when the expected type is explicitly stated -- Fixing incorrect or overly broad annotations when the correct type is provided - -### Not Suitable for Good First Issues -- Inferring types by interpreting code behavior -- Cross-file or large-scale typing refactors -- Resolving complex type-system issues - ---- - -### Documentation Improvements - -Documentation tasks must be **explicitly scoped and instruction-driven**. - -### Suitable for Good First Issues -- Fixing identified typos or grammar issues -- Replacing text with a provided version -- Making explicitly described changes to docstrings, comments, or print statements -- Renaming variables or examples when new names are provided -- Splitting or combining examples when explicitly instructed - -### Not Suitable for Good First Issues -- Writing new documentation -- Adding explanations that require interpreting code behavior -- Deciding what should be documented -- Choosing which steps or details should exist - ---- - -### Test Improvements - -> ⚠️ Most test-related work is better suited for **Beginner or Intermediate Issues**. - -### Suitable for Good First Issues (rare, explicit cases only): -- Adding a clearly specified assertion to an existing test -- Small mechanical edits with no test-design decisions - -### Not Suitable for Good First Issues -- Creating new test files -- Designing new test cases -- Extending coverage based on interpretation - ---- - -## Summary: What Is NOT a Good First Issue - -- ❌ Issues without a clearly defined or provided solution -- ❌ Tasks requiring interpretation, investigation, or initiative -- ❌ Changes to `src` functionality that affect behavior -- ❌ Creating new documentation, examples, or tests -- ❌ Work spanning multiple files or subsystems - ---- - -## Maintainer Guidance - -### Label an issue as GFI if it: - -- ✅ Touches a single file or clearly defined location -- ✅ Has a clear, well-defined scope -- ✅ Requires no domain or protocol knowledge -- ✅ Can be reviewed quickly -- ✅ Has low risk of unintended side effects -- ✅ Includes explicit or step-by-step instructions - -### Do NOT label an issue as GFI if it: - -- ❌ Touches multiple subsystems -- ❌ Changes SDK behavior or contracts -- ❌ Requires domain or protocol knowledge -- ❌ Could introduce subtle side effects -- ❌ Requires extensive review or testing -- ❌ Requires interpretation or design decisions - -Such issues are better labeled as **Beginner Issues**. - ---- - -## Important Reminders - -1. Good First Issues are often promoted automatically, making them highly visible -2. Good First Issues are typically self-assigned, so they must be achievable by anyone -3. Quality matters more than quantity — fewer, safer GFIs are better -4. Every GFI should clearly define what “done” means -5. Link to relevant documentation whenever possible to help contributors succeed - ---- - -## Additional Resources - -- [Contributing Guide](../../CONTRIBUTING.md) -- [DCO Signing Guide](../sdk_developers/signing.md) -- [Changelog Entry Guide](../sdk_developers/changelog_entry.md) -- [Discord Community](../discord.md) -- [Community Calls](https://zoom-lfx.platform.linuxfoundation.org/meeting/92041330205?password=2f345bee-0c14-4dd5-9883-06fbc9c60581) diff --git a/docs/maintainers/intermediate_issue_guidelines.md b/docs/maintainers/intermediate_issue_guidelines.md deleted file mode 100644 index 5a8c5e9e2..000000000 --- a/docs/maintainers/intermediate_issue_guidelines.md +++ /dev/null @@ -1,204 +0,0 @@ -# Intermediate Issue Guidelines — Hiero Python SDK - -## How to Use This Document - -This guide supports maintainers and issue creators who use the **Intermediate** label -in the Hiero Python SDK repository. - -It helps: - -**Issue creators:** -- Describe moderately complex tasks clearly -- Set expectations around scope and independence -- Provide enough context without over-prescribing solutions - -**Maintainers:** -- Apply the Intermediate label consistently -- Keep issue difficulty levels clear and helpful - -This isn’t a rulebook, and it’s not meant to limit what kinds of contributions are welcome. -All contributions — from small fixes to major improvements — are valuable to the Hiero project. - -The **Intermediate** label highlights work that involves investigation, reasoning, -and ownership — while staying well-scoped and safe to review. - ---- - -## Purpose - -Intermediate Issues represent the **next step after Beginner Issues**. - -They’re a great fit for contributors who: - -- Are comfortable navigating the codebase -- Enjoy investigating how things work -- Are ready to take more ownership of their changes - -These issues help contributors grow their confidence in: - -- Understanding existing behavior -- Making thoughtful, localized changes -- Working more independently - ---- - -## What to Expect - -Intermediate Issues are designed for contributors who: - -- Are familiar with the Python SDK structure -- Can read and reason about existing implementations -- Are comfortable working across multiple files -- Can ask focused questions when needed - -These issues usually involve more exploration than Beginner Issues, -but still have clear goals and boundaries. - ---- - -## How Intermediate Issues Usually Feel - -Intermediate Issues often: - -- Involve multiple related files -- Require understanding existing behavior -- Leave room for thoughtful implementation choices -- Stay focused on a specific, well-defined goal - -They’re a great fit for contributors who enjoy learning by digging into the code. - ---- - -## Common Types of Intermediate Work - -Here are examples of tasks that often fit well at this level: - -### Core SDK Changes -- Small-to-medium behavior changes with clear intent -- Bug fixes that require investigating existing logic -- Localized refactors for clarity or maintainability -- Improvements to existing APIs without breaking contracts - -### Refactors & Code Quality -- Refining overly broad or imprecise type hints -- Reducing duplication or complexity -- Improving internal abstractions with clear justification - -### Documentation & Guides -- Writing new documentation for existing features -- Clarifying developer guides based on real usage -- Documenting non-obvious workflows -- Updating docs to reflect recent changes - -### Examples & Usability -- Creating new examples for existing features -- Improving examples based on user feedback -- Refactoring examples to demonstrate best practices - -### Tests -- Adding new tests for existing functionality -- Extending coverage for edge cases -- Refactoring tests for clarity and structure - ---- - -## Usually Not Good Fits - -- Purely mechanical tasks -- Fully scripted changes -- Large architectural redesigns -- Long-term, multi-phase projects -- Work requiring deep protocol or DLT expertise - -These tasks may be a better fit for **Good First Issue** or **Beginner** labels. - -If a task: - -- Involves major design decisions -- Affects core architecture or APIs - -…it may be a better fit for the **Advanced** label. - ---- - -## Typical Scope & Time - -Intermediate Issues are usually: - -- ⏱ **Estimated time:** 1–3 days -- 📄 **Scope:** Multiple related files -- 🧠 **Challenge level:** Investigation, reasoning, and ownership - -They’re designed to be achievable in a single pull request. - ---- - -## Example: A Well-Formed Intermediate Issue - -### Add optional child receipt support to TransactionReceiptQuery - -The Python SDK’s `TransactionReceiptQuery` currently returns only the parent -transaction receipt, even when child receipts are available. - -The mirror node API supports returning child receipts, and similar query types -in the SDK already support optional configuration flags. - -This makes it harder to inspect scheduled or child transactions without -additional manual queries. - -Relevant files: -- `hiero_sdk/query/transaction_receipt_query.py` -- `examples/query/transaction_receipt_query.py` - -### Expected Outcome - -Add an optional configuration flag that allows callers to request child receipts. - -The change should: - -- Be opt-in (default behavior stays the same) -- Reuse existing receipt parsing logic -- Follow existing query configuration patterns -- Avoid breaking public APIs - -Example usage: - -```python -receipt = ( - TransactionReceiptQuery() - .set_transaction_id(tx_id) - .set_include_children(True) - .execute(client) -) -``` -### Implementation Notes - -Likely steps: -- Add an optional boolean flag (e.g. include_children) -- Propagate the flag to the mirror node request -- Update response parsing to include child receipts -- Update the example file -- Add or adjust unit tests -- Similar patterns exist in other query classes with optional flags. - -## Support & Collaboration -- Intermediate Issues are supported through: -- Issue and PR discussions -- Maintainer and community feedback - -Support focuses on: -- Helping contributors reason about existing behavior -- Clarifying boundaries and constraints -- Ensuring changes stay safe and well-scoped -- The goal is to build confidence while protecting the stability of the SDK. - -Maintainer Guidance -- An issue is often a good fit for the Intermediate label when it: -- Builds naturally on Beginner Issues -- Requires investigation and interpretation -- Has clear intent but multiple valid approaches -- Includes enough context to avoid breaking changes -- Can be completed in a single PR - -Intermediate Issues are about growing skills — -through exploration, reasoning, and thoughtful ownership. \ No newline at end of file diff --git a/docs/sdk_developers/automations/next-issue-recommendation-bot.md b/docs/sdk_developers/automations/next-issue-recommendation-bot.md deleted file mode 100644 index 1547645d9..000000000 --- a/docs/sdk_developers/automations/next-issue-recommendation-bot.md +++ /dev/null @@ -1,156 +0,0 @@ -# Next Issue Recommendation Bot - -## Overview - -The Next Issue Recommendation Bot is an automated GitHub Actions workflow designed to improve contributor retention by recommending relevant issues to contributors after their first successful pull request merge. This bot specifically targets contributors who complete "Good First Issue" or "beginner" level issues, helping them find their next contribution opportunity. - -## Trigger Conditions - -The bot triggers under the following conditions: - -1. **Automatic Trigger**: When a pull request is merged (`pull_request_target` event with `closed` type) - -The workflow only runs when: -- The pull request has been merged (`github.event.pull_request.merged == true`) -- The merged PR is linked to an issue with "Good First Issue" or "beginner" labels -- The linked issue is not labeled as "intermediate" or "advanced" - -## Recommendation Logic - -### Issue Detection - -The bot parses the pull request body to find linked issues using regex patterns that match: -- `Fixes #ISSUE_NUMBER` -- `Closes #ISSUE_NUMBER` -- `Resolves #ISSUE_NUMBER` -- `Fix #ISSUE_NUMBER` -- `Close #ISSUE_NUMBER` -- `Resolve #ISSUE_NUMBER` - -### Recommendation Strategy - -1. **For Good First Issue completers**: - - First searches for unassigned issues with "beginner" label - - Falls back to unassigned "Good First Issue" issues if no beginner issues found - -2. **For beginner issue completers**: - - Searches for unassigned issues with "beginner" label - - Falls back to unassigned "Good First Issue" issues if no beginner issues found - -3. **Fallback behavior**: - - If no repository issues are available, provides link to organization-wide good first issues - - Limits recommendations to up to 5 issues to avoid overwhelming contributors - -## Comment Content - -The bot posts a congratulatory comment that includes: - -- **Congratulations message**: Thank you and encouragement for the contribution -- **Recommended issues**: List of up to 5 relevant issues with: - - Issue title and direct link - - Brief description (truncated to 150 characters) -- **Repository engagement**: - - Direct link to star the repository - - Direct link to watch the repository for notifications -- **Community resources**: Link to Discord community for questions -- **Fallback message**: Organization-wide good first issues link if no repo issues available - -### Example Comment Structure - -```markdown - - -🎉 **Congratulations on your first merged contribution!** - -Thank you for your contribution to the Hiero Python SDK! We're excited to have you as part of our community. - -Here are some beginner-level issues you might be interested in working on next: - -1. [Issue Title](https://github.com/owner/repo/issues/123) - Brief description of the issue... - -2. [Another Issue](https://github.com/owner/repo/issues/456) - Another brief description... - -🌟 **Stay connected with the project:** -- ⭐ [Star this repository](https://github.com/owner/repo) -- 👀 [Watch this repository](https://github.com/owner/repo/watchers) - -We look forward to seeing more contributions from you! If you have any questions, feel free to ask in our [Discord community](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/discord.md). - -From the Hiero Python SDK Team 🚀 -``` - -## Idempotent Behavior - -The bot includes duplicate prevention by: - -- Wrapping comments with HTML marker `` -- Checking existing PR comments for the marker before posting -- Skipping if a comment already exists -- This ensures only one recommendation comment per PR - -## Technical Implementation - -### Workflow File - -**Location**: `.github/workflows/bot-next-issue-recommendation.yml` - -**Key features**: -- Uses pinned action versions per project conventions -- Minimal permissions (`pull-requests: write`, `issues: read`, `contents: read`) -- Concurrency control to prevent duplicate runs - -### Script File - -**Location**: `.github/scripts/bot-next-issue-recommendation.js` - -**Key components**: -- GitHub REST API integration for issue and comment operations -- Regex parsing for linked issue detection -- Search queries with label filtering -- Error handling and logging - -## Testing - -The bot can be tested through: - -1. **Fork testing**: Test workflow behavior in forks before production deployment -2. **GitHub CLI testing**: Local testing with appropriate environment variables - -**Note**: The workflow only triggers automatically when PRs are merged. Manual testing requires creating test PRs and merging them in a test environment. - -## Permissions - -The workflow requires minimal permissions: -- `pull-requests: write` - To post comments on pull requests -- `issues: read` - To fetch issue details and search for recommendations -- `contents: read` - To access the script file - -## Troubleshooting - -### Common Issues - -1. **No linked issues found**: Ensure PR body contains "Fixes #123" or similar pattern -2. **Permission errors**: Verify workflow has required permissions -3. **Rate limiting**: GitHub API limits are handled by the GitHub Actions runner -4. **Duplicate comments**: Bot checks for existing markers to prevent duplicates - -### Debug Information - -The bot provides detailed logging: -- PR number and dry-run status -- Linked issue detection results -- Issue labels found -- Search queries used -- Number of recommended issues found -- Comment posting status - -## Future Enhancements - -Potential improvements to consider: -- Support for custom recommendation criteria -- Integration with contributor statistics -- Personalized recommendations based on contribution history -- Support for multiple issue linking patterns -- Analytics on bot effectiveness and contributor retention diff --git a/docs/sdk_developers/changelog_entry.md b/docs/sdk_developers/changelog_entry.md deleted file mode 100644 index 7bfd84847..000000000 --- a/docs/sdk_developers/changelog_entry.md +++ /dev/null @@ -1,182 +0,0 @@ -# Changelog Entry Guide - -This document explains how to create proper changelog entries for the Hiero Python SDK. - -## Table of Contents - -- [Why Changelog Entries Matter](#why-changelog-entries-matter) -- [Required Format](#required-format) -- [Changelog Sections](#changelog-sections) -- [Step-by-Step Guide](#step-by-step-guide) -- [Examples](#examples) - -## Why Changelog Entries Matter - -**Every pull request MUST include a changelog entry.** - -The changelog is the first place users look to understand what's new, what's fixed, and what's changed in each release. A well-written changelog entry helps users quickly understand the impact of your contribution. - -## Required Format - -Your changelog entry must: - -1. **Link to the issue** - Include a reference to the issue your PR solves -2. **Use clear, descriptive language** - Be concise but informative -3. **Be 1-2 sentences** - Keep it brief and focused -4. **Go under [Unreleased]** - Add your entry at the top of the file, in the appropriate section under `[Unreleased]` -5. **Use proper markdown** - Follow the bullet point format - -## Changelog Sections - -The `[Unreleased]` section is divided into three categories. Choose the one that best fits your change: - -### Added -For new features, functionality, or capabilities added to the SDK. - -**Examples:** -- New API methods -- New query types -- New transaction types -- New utility functions - -### Changed -For modifications to existing functionality that change behavior but aren't bug fixes. - -**Examples:** -- Refactored code structure -- Updated dependencies -- Modified function signatures -- Performance improvements -- Updated documentation - -### Fixed -For bug fixes that resolve incorrect behavior. - -**Examples:** -- Resolved errors or exceptions -- Corrected incorrect return values -- Fixed edge cases -- Patched security vulnerabilities - -## Step-by-Step Guide - -1. **Open `CHANGELOG.md`** in the repository root - -2. **Find the `[Unreleased]` section** at the top of the file - -3. **Choose the appropriate subsection** (Added, Changed, or Fixed) - -4. **Add your entry as a new bullet point** at the top of that subsection - -5. **Format your entry** as: - ```markdown - - Brief description of your change (#IssueNumber) - ``` - -6. **Ensure it's descriptive** - Readers should understand what changed and why it matters - -## Examples - -### ✅ Good Examples - -#### Good: Clear and Descriptive -```markdown -## [Unreleased] - -### Changed -- Refactor `query_balance.py` into modular, reusable functions with `setup_client()`, `create_account()`, `get_balance()`, `transfer_hbars()`, and `main()` for improved readability, maintainability, and error handling (#123) -``` - -**Why this is good:** -- Links to the issue (#123) -- Describes what was refactored -- Lists the specific functions created -- Explains the benefits (readability, maintainability, error handling) -- Placed correctly under [Unreleased] → Changed - -#### Good: Bug Fix -```markdown -## [Unreleased] - -### Fixed -- Resolve `TypeError` in `transfer_transaction.py` when passing `None` as memo parameter (#456) -``` - -**Why this is good:** -- Links to the issue -- Specifies the error type -- Identifies the affected file -- Describes the problematic scenario - -#### Good: New Feature -```markdown -## [Unreleased] - -### Added -- Add support for HIP-### token association transactions with automatic fee calculation (#789) -``` - -**Why this is good:** -- Links to the issue -- Clearly states what was added -- Mentions a key feature (automatic fee calculation) - -### ❌ Bad Examples - -#### Bad: Not Informative -```markdown -## [Unreleased] - -### Changed -- Refactor `query_balance.py` -``` - -**Why this is bad:** -- No issue link -- Doesn't explain what was refactored or why -- Too vague - users can't understand the impact - -#### Bad: Wrong Placement (Version Number Instead of Unreleased) -```markdown -## [0.1.6] - 2025-10-21 - -### Changed -- Refactor `query_balance.py` into modular, reusable functions (#123) -``` - -**Why this is bad:** -- Added under a released version instead of [Unreleased] -- Version numbers and dates are added by maintainers during release -- Your entry should always go under [Unreleased] - -#### Bad: No Issue Reference -```markdown -## [Unreleased] - -### Fixed -- Fix bug in transaction signing -``` - -**Why this is bad:** -- No issue link -- Too vague about what bug was fixed -- Doesn't help users understand if it affects them - -## Common Mistakes to Avoid - -1. **Don't add entries to released versions** - Always use `[Unreleased]` -2. **Don't forget the issue number** - Every entry needs a link like `(#123)` -3. **Don't write paragraphs** - Keep it to 1-2 sentences -4. **Don't be too technical** - Write for SDK users, not just developers -5. **Don't skip the changelog** - It's required for all PRs - -## Need Help? - -If you're unsure about your changelog entry: - -1. Look at recent entries in `CHANGELOG.md` for inspiration -2. Ask in your pull request for feedback -3. Review this guide again -4. Check other documentation files in `docs/sdk_developers/` - -Remember: A good changelog entry helps thousands of developers understand your contribution! diff --git a/docs/sdk_developers/checklist.md b/docs/sdk_developers/checklist.md index facffb729..e2d8e0ace 100644 --- a/docs/sdk_developers/checklist.md +++ b/docs/sdk_developers/checklist.md @@ -40,10 +40,10 @@ Navigate to your PR page on GitHub and use the **Checks** and **Commits** tabs t | Requirement | GitHub Location | Status to Look For | Action if Failed | | :--- | :--- | :--- | :--- | -| **Commit Signature** | **Commits Tab** | Must show **"Verified"** (Green badge) | See **[Signing Guide](signing.md)** for how to set up GPG and fix unverified commits. | -| **DCO Check** | **Checks Tab** | The "DCO" or "License" check must show a **Green Checkmark**. | See **[Signing Guide](signing.md)** to ensure your commits have the DCO sign-off (`-s`). | +| **Commit Signature** | **Commits Tab** | Must show **"Verified"** (Green badge) | See **[Signing Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/signing.md)** for how to set up GPG and fix unverified commits. | +| **DCO Check** | **Checks Tab** | The "DCO" or "License" check must show a **Green Checkmark**. | See **[Signing Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/signing.md)** to ensure your commits have the DCO sign-off (`-s`). | | **Tests Pass (CI)** | **Checks Tab** (Workflows like 'Integration Tests') | All required tests must show a **Green Checkmark**. | View the logs for the failing check to debug the error locally. | -| **Changelog Formatting** | **Checks Tab** ('PR Formatting / Changelog Check') | Must show a **Green Checkmark**. | Correct the `CHANGELOG.md` and force push. See **[Changelog Guide](changelog_entry.md)**. | +| **Changelog Formatting** | **Checks Tab** ('PR Formatting / Changelog Check') | Must show a **Green Checkmark**. | Correct the `CHANGELOG.md` and force push. See **[Changelog Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/changelog-guide.md)**. | ### The Files Changed Tab @@ -54,6 +54,6 @@ The **Files Changed Tab** shows the exact **difference** between your branch and ## Need Help? -- **Signing issues?** → [Signing Guide](signing.md) -- **Merge conflicts?** → [Merge Conflicts Guide](merge_conflicts.md) -- **Changelog format?** → [Changelog Guide](changelog_entry.md) \ No newline at end of file +- **Signing issues?** → [Signing Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/signing.md) +- **Merge conflicts?** → [Merge Conflicts Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/merge_conflicts.md) +- **Changelog format?** → [Changelog Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/changelog-guide.md) diff --git a/docs/sdk_developers/merge_conflicts.md b/docs/sdk_developers/merge_conflicts.md deleted file mode 100644 index 3ba6d459c..000000000 --- a/docs/sdk_developers/merge_conflicts.md +++ /dev/null @@ -1,256 +0,0 @@ -## Handling Conflicts - -Merge conflicts are caused by working on out-dated versions of the codebase, or another developer merging a change involving similar parts of the codebase to you. - -> ⚠️ **Avoid Merge Conflicts** by syncing your branch regularly [Sync Guide](rebasing.md) - -## Table of Contents - -- [Handling Conflicts](#handling-conflicts) -- [Resolving CHANGELOG.md Conflicts Using GitHub's Web Editor](#resolving-changelogmd-conflicts-using-githubs-web-editor) -- [Step-by-Step Guide to Resolve Merge Conflicts Locally](#step-by-step-guide-to-resolve-merge-conflicts-locally) - - [1. See which files are conflicted](#1-see-which-files-are-conflicted) - - [2. Understand what conflicts](#2-understand-what-conflicts) - - [3. Decide what the final code should be](#3-decide-what-the-final-code-should-be) - - [4. Resolve conflicts in VS Code (recommended)](#4-resolve-conflicts-in-vs-code-recommended) - - [Steps to resolve in VS Code](#steps-to-resolve-in-vs-code) - - [1. Open the conflicted file in VS Code](#1-open-the-conflicted-file-in-vs-code) - - [2. Look at both the Incoming and Current changes](#2-look-at-both-the-incoming-change-left-and-current-change-right-panels) - - [3. Edit the Result pane](#3-in-the-result-lower-pane-edit-the-file-so-it-contains-the-correct-final-version) - - [4. Save the resolved file](#4-save-the-lower-pane-file-once-there-are-no-more-merge-conflicts-to-resolve-in-this-file) - - [5. Stage the resolved files](#5-click-the-add-button-next-to-the-file-to-resolve-conflicts-or) - - [6. Continue the rebase](#6-continue-the-rebase) - - [7. Resolve remaining conflicts](#7-if-there-are-more-conflicts-in-other-files-vs-code-will-automatically-move-you-to-the-next-one-repeat-until-no-conflicts-remain) - - [8. Push changes](#8-push-changes) - - [Common issues](#common-issues) - - [If you need to stop](#if-you-need-to-stop) - - [What NOT to do](#what-not-to-do) - - [When to Use This Method](#when-to-use-this-method) - - [Steps](#steps) -- [Recovery Tips](#recovery-tips) - - [If you are completely stuck](#if-you-are-completely-stuck) -- [Helpful Resources](#helpful-resources) - - -## Resolving CHANGELOG.md Conflicts Using GitHub's Web Editor - -Changelog conflicts in CHANGELOG.md are very common in this repository because multiple pull requests frequently add new entries to the "Unreleased" section at the same time. - -For these conflicts, there is a much simpler alternative to the full local rebase process: you can resolve them directly in your Pull Request on GitHub using the built-in web editor. No local setup or force push is required. - -**Strong Recommendation**: Use the local VS Code rebase method (described below) to ensure full signing compliance. Use the web editor only if you are prepared to amend and re-sign the resolution commit locally afterward. - -### When to Use This Method - -- The conflict is only (or primarily) in `CHANGELOG.md`. -- You want to keep both sets of changes — this is almost always the correct choice for changelogs, as they are designed to accumulate all entries over time. - -**Important**: The warnings above about not blindly accepting changes apply to code files. For CHANGELOG.md, "accepting both" is safe and recommended. - -### Steps - -1. In your PR, go to **Files changed** and scroll to the bottom. In the merge‑conflict banner, click **Resolve conflicts** to open the web editor. -2. In GitHub's web-based editor: - - Conflicted sections are highlighted (usually in red/yellow). - - You'll see **Incoming change** (from main) and **Current change** (from your branch) marked in red/highlighted areas. - -3. **For a changelog conflict**: - - Click **Accept both** (if the button is available) — this combines all the bullet-point entries perfectly. - - If no "Accept both" button appears, manually remove the conflict markers (`<<<<<<< HEAD`, `=======`, `>>>>>>> your-branch`) and keep all entries from both sides. - - Optionally, sort or group similar entries for neatness. - -4. Once all conflicts are resolved, click **Mark as resolved** at the top of the editor. - -5. You'll see a **Sign off and Commit** section: - - Review your commit message - - Click **Commit merge** (or **Commit directly to...** depending on your GitHub UI). - -6. Your PR will update automatically, and the conflict will be resolved. - -This method is especially beginner-friendly and avoids the more advanced local rebase steps. - -For more details on GitHub's web-based editor, see: [The GitHub.dev web-based editor](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor). -**Example**: See [PR `#1589`](https://github.com/hiero-ledger/hiero-sdk-python/pull/1589) for a real example of resolving a CHANGELOG.md conflict using this method. - - -## Step-by-Step Guide to Resolve Merge Conflicts Locally - -### 1. See which files are conflicted -```bash -git checkout mybranch -git status -``` - -### 2. Understand what conflicts -You will see sections like: - -```text -<<<<<<< HEAD -code from main -======= -your branch’s code ->>>>>>> mybranch -``` - -### 3. Decide what the final code should be - -Have a vision of what you'd like the final code to look like, given what is currently on main and what you'd like to propose. - -> ⚠️ **WARNING: Do not blindly accept both changes**. This often leads to problems. -> ⚠️ **WARNING: Do not blindly accept incoming**. This often leads to problems. -> ⚠️ **WARNING: Do not blindly accept existing**. This often leads to problems. - -Merge conflicts require: - -✅ Human interpretation - -Sometimes you'll be: -- Accepting both incoming and current -- Accepting only incoming -- Accepting only current -- Accepting **parts** of both incoming and current - -Generally, you want to keep all changes that were merged to main, but additionally, layer on your changes. - - -> ✅ **Resolving Conflicts Requires Human Interpretation**. Merge conflicts require thinking about what the final piece should be, should it include both changes? some of each? none of one? - -> ✅ **Resolving Conflicts Requires Human Edits**. Merge conflicts require manually editing the code. - - -### 4. Resolve conflicts in VS Code (recommended): -Once you understand you have a merge conflict and have a vision of the the final document, we recommend using VS code. - - -VS Code makes solving merge-conflicts more easier with a 3-pane interface for resolving conflicts: - --> Incoming Change → code from main (left/top) - --> Current Change → code from your branch (right/top) - --> Result → the lower/third pane, where you create the final merged file. - -You want to accept or reject content from the top left and top right panes, and edit the final pane in the bottom so the final code submission reasonably resolves the issue while respecting the work of others. - -#### Steps to resolve in VS Code: - -##### 1. Open the conflicted file in VS Code. - -##### 2. Look at both the Incoming Change (left) and Current Change (right) panels. - -##### 3. In the Result (lower pane), edit the file so it contains the correct final version. - --> Sometimes keep Incoming (main) - --> Sometimes keep Current (your branch) - --> Often, combine both parts and edit the code manually. -If the conflict is resolved correctly, VS Code will mark it as fixed. - -##### 4. Save the lower pane file once there are no more merge conflicts to resolve in this file. - -##### 5. Click the add button next to the file to resolve conflicts or: -```bash -git add . -``` - -##### 6. Continue the rebase -```bash -git rebase --continue -``` - -##### 7. If there are more conflicts in other files, VS Code will automatically move you to the next one. Repeat until no conflicts remain. - -⚠️ Do NOT just click “Accept All Incoming” or “Accept All Current” — that usually **deletes** or **corrupts** important code. - -Once the rebase operation completes, your commits will be layered on top of main. It means your commit history will look “different” and you may even see changes to commits from other authors — this is expected, since rebase rewrites history. - -##### 8. Push changes -If you already have an open Pull Request, you will need to update it with a **force push**. - -Before pushing, double-check that your commits are both DCO signed and GPG verified: - -```bash -git log -n 5 --pretty=format:'%h %an %G? %s' -``` -Replacing 5 with the number of commits backwards in history to check. - -Ensure you see: -`G` = Good (valid signature) - -then: -```bash -git push --force-with-lease -``` - -**Tip**: To be safe, create a backup branch before force pushing: -```bash -git checkout -b mybranch-backup -``` - -### Common issues -Message: “No changes – did you forget to use git add?” -→ This means you resolved the conflicts but forgot to stage them. Run git add . and try again. - -Message: “Are you sure you want to continue with conflicts?” -→ This means some conflicts are still unresolved or you did not save the files properly. -Double-check your files in VS Code, make sure they are saved, and resolve any remaining conflict markers (<<<<<<<, =======, >>>>>>>). - - -### If you need to stop -```bash -git rebase --abort -``` - -**Tip**: At each conflict: resolve → save → stage → continue. Repeat until all conflicts are gone. - -### What NOT to do -1. ❌ Do not run git merge main -→ This creates messy merge commits. Always rebase instead. - -2. ❌ Do not merge into your local main -→ Keep main as a clean mirror of upstream/main. - -3. ❌ Do not open PRs from your fork’s main -→ Always create a feature branch for your changes. - -At each conflict instance, you'll have to repeat: fix the conflict, stage the files and continue rebasing. - -## Recovery Tips: - -- Undo the last rebase commit, but keep changes staged (while still in rebase): -If you are in the middle of a rebase and realize the last step went wrong, you can undo it while keeping changes staged: -```bash -git reset --soft HEAD~i -``` - -Note: The number after HEAD~ refers to how many commits you want to go back. - -For example: -HEAD~1 → go back 1 commit -HEAD~3 → go back 3 commits -HEAD~5 → go back 5 commits - -### If you are completely stuck -Sometimes a rebase can get too messy to fix conflict by conflict. In that case, it’s often easier to start fresh: - -1. Abort the rebase to stop where you are: -```bash -git rebase --abort -``` - -2. Reset your fork's main to the upstream main and layer your commits on top of that: -``` bash -git checkout main -git reset --hard upstream/main -git push origin main --force-with-lease -git checkout mybranch -git rebase upstream/main -S -``` - -⚠️ Use git stash only if you really want to save some local changes that aren’t yet committed. In most cases, if the rebase is failing, it’s safer to abort or reset rather than reapplying a stash of broken work. - -### Helpful Resources -- [Signing Guide](signing.md) -- [Rebasing Guide](rebasing.md) -- [Discord](../discord.md) \ No newline at end of file diff --git a/docs/sdk_developers/rebasing.md b/docs/sdk_developers/rebasing.md deleted file mode 100644 index 58f35138d..000000000 --- a/docs/sdk_developers/rebasing.md +++ /dev/null @@ -1,65 +0,0 @@ -# Rebasing - -## Keeping Your Fork and Branch Up to Date with Main - -Rebases keep your branch in-sync with the upstream main, meaning you are working on the latest version of the codebase. This means the methods you are using are up-to-date and you avoid merge-conflicts. - - -### Step by Step Guide to Rebase - -#### 1. Add the original repo as a remote called "upstream" -Only do this once per repository clone. - -If not already done: -```bash -git remote add upstream https://github.com/hiero-ledger/hiero-sdk-python.git -``` - -#### 2. Sync your main on your fork -Each time you want to sync: -- Sync your fork's main with the upstream main changes: - -```bash - git checkout main - git fetch upstream - git pull upstream main - git push origin main -``` - -You can also do this by visiting your repository "https://github.com/YOUR_GITHUB_NAME/hiero-website" and clicking the sync fork button which is a few lines from the top near the right. Then pull these changes locally in Github Desktop. - -#### 3. Sync your working branch - -Your fork’s `main` branch is now up to date, but **your working branch is not**. - -To bring your branch in sync with the latest changes, apply a **rebase**. -This keeps history clean and ensures your commits remain eligible for review. - -To rebase: - -```bash -git checkout mybranch -git rebase main -S -``` - -> ⚠️ **Always include the -S flag** -> ⚠️ **Do NOT merge `main` into your branch** - -### 4. Verify Sign Status -Verify after the rebase operation, your commits are still signed correctly: - -```bash -git log -n 5 --pretty=format:'%h %an %G? %s' -``` -Replacing 5 with the number of commits you want to check back in history. -You should see `G` (valid signature). If you experience signing issues, read [Signing Guide](signing.md) - -## Handling Conflicts: -If conflicts occur during rebase, See [Merge Conflict Guide](./merge_conflicts.md) for detailed guidance. - -> ⚠️ **Regularly** rebase your branch to avoid merge conflicts - -### Helpful Resources -- [Signing Guide](signing.md) -- [Merge Conflict Guide](./merge_conflicts.md) -- [Discord](../discord.md) \ No newline at end of file diff --git a/docs/sdk_developers/signing.md b/docs/sdk_developers/signing.md deleted file mode 100644 index a08dc487f..000000000 --- a/docs/sdk_developers/signing.md +++ /dev/null @@ -1,191 +0,0 @@ -# Commit Signing Guidelines (DCO + GPG) - -**Both DCO sign-off and GPG signature signed commits** are required for all pull requests to be merged successfully. - -This guide makes it as easy as possible for you to set up your GPG key and DCO and GPG sign your commits. - ---- - -## Table of Contents - -- [Commit Signing Guidelines (DCO + GPG)](#commit-signing-guidelines-dco--gpg) -- [Definitions](#definitions) -- [Step-by-Step Setup](#step-by-step-setup) - - [1. Generate a GPG Key](#1-generate-a-gpg-key) - - [2. Add Your GPG Key to GitHub](#2-add-your-gpg-key-to-github) - - [3. Configure Git to Use Your GPG Key](#3-configure-git-to-use-your-gpg-key) - - [4. Make Signed Commits](#4-make-signed-commits) - - [5. Verify Signed Status of Commits](#5-verify-signed-status-of-commits) -- [Final Checklist](#final-checklist) -- [Fixing Unsigned Commits](#fixing-unsigned-commits) - - [1. Soft Reverting Commits (Recommended for New Contributors)](#1-soft-reverting-commits-recommended-for-new-contributors) - - [2. Retroactively Signing Commits](#2-retroactively-signing-commits) -- [Rebasing and Signing](#rebasing-and-signing) -- [Still Need Help?](#still-need-help) - - ---- - -## Definitions - -| Signature | Flag | Purpose | GitHub Check | -| :--------------- | :--- | :-------------------------------------------------------------- | :--------------- | -| **DCO Sign-off** | `-s` | Confirms legal right to contribute code (required by CI bot). | DCO Check | -| **GPG Signature**| `-S` | Proves you are the author of the commit (required by CI bot, requires GPG setup). | Verified Badge | - -**CRITICAL WARNING:** To pass the DCO check and achieve the "Verified" status, **all commits** must be signed using **both** the `-S` and `-s` flags together. - - ---- - -## Step-by-Step Setup - -### 1. Generate a GPG Key - -If you don't already have a GPG key: - -```bash -gpg --full-generate-key -``` - -Choose: -* Kind: ECC (sign and encrypt) *default* -* Elliptic curve: Curve 25519 *default* -* Expiration: 0 *default* (does not expire) -* Name, Email: Must match your GitHub email -* Passphrase: Set a strong passphrase that you'll need to remember - -Learn more [GPG key set-up documentation on GitHub](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key) - -Once created, list your keys: - -```bash -gpg --list-secret-keys --keyid-format LONG -``` - -Copy the key ID (looks like `34AA6DBC`). - ---- - -### 2. Add Your GPG Key to GitHub - -Export your GPG public key: - -```bash -gpg --armor --export YOUR_KEY_ID -``` - -Paste the output into GitHub: -* [Add GPG key on GitHub](https://github.com/settings/gpg/new) - ---- - -### 3. Configure Git to Use Your GPG Key - -```bash -git config --global user.signingkey YOUR_KEY_ID -git config --global commit.gpgsign true -``` - ---- - -### 4. Make Signed Commits - -**All commits must be signed using both DCO and GPG.** -Each time you create a commit, use -S and -s flags like this: - -```bash -git commit -S -s -m "chore: your commit message" -``` - -* `-S` = GPG sign -* `-s` = DCO sign-off - -> ⚠️ Ensure **every commit** in your branch follows this rule. - ---- - -### 5. Verify Signed Status of Commits - -To check that your commits are signed correctly: - -```bash -git log --show-signature -``` - -* Ensure each commit shows both **GPG verified** and **DCO signed-off**. - -For a quick check of recent n commits: -Note how many commits you have added, and replace 5 with that. - -```bash -git log -n 5 --pretty=format:'%h %an %G? %s' -``` -Legend: - -- G = Good (valid signature - you want to see `G`) -- B = Bad (invalid signature) -- U = Unknown (not signed) -- E = Signed (but not verifiable locally) ---- - -## Final Checklist - -* [ ] All commits signed with `-S`. -* [ ] DCO added with `-s` -* [ ] GPG key added to GitHub - ---- - -## Fixing Unsigned Commits - -If you accidentally forgot to sign commits, there are **two ways to fix them**: - -### 1. Soft Reverting Commits (Recommended for New Contributors) - -Soft revert the impacted commits while keeping changes locally: - -```bash -git reset --soft HEAD~n -``` - -* `HEAD~n` = number of commits to go back -* Example: To fix the last 3 commits: `git reset --soft HEAD~3` - -Then, recommit each commit with proper signing: - -```bash -git commit -S -s -m "chore: your commit message" -``` - ---- - -### 2. Retroactively Signing Commits - -Alternatively, you can **amend commits retroactively**: - -```bash -git commit --amend -S -s -git rebase -i HEAD~n # For multiple commits -git push --force-with-lease -``` -This is difficult and you may run into problems, for example, if you have merged from main. - -## Rebasing and Signing - -Rebase operations will be required when your branch is behind the upstream main. We do not recommend merging from main, rebasing is strongly suggested. See [Rebasing Guide](./rebasing.md) for instructions on how to keep your main branch up to date and how to rebase. - -When rebasing, you must use this command to ensure your commits remain DCO and GPG signed: - -```bash -git rebase main -S -``` - -> **Note:** `git push --force-with-lease` safely updates the remote branch without overwriting others' changes. - ---- - -## Still Need Help? - -* Refer to [GitHub's GPG Docs](https://docs.github.com/en/authentication/managing-commit-signature-verification) -* Ask on the **Hiero [Discord](../discord.md)** \ No newline at end of file diff --git a/docs/sdk_developers/testing.md b/docs/sdk_developers/testing.md index 939404560..7749197f0 100644 --- a/docs/sdk_developers/testing.md +++ b/docs/sdk_developers/testing.md @@ -1232,7 +1232,7 @@ If you encounter issues or have questions: ### Useful Resources - **Contributing Guide**: [CONTRIBUTING.md](../../CONTRIBUTING.md) -- **Commit Signing Guide**: [signing.md](signing.md) +- **Commit Signing Guide**: [Signing Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/signing.md) - **pytest Documentation**: https://docs.pytest.org/ - **Hedera Documentation**: https://docs.hedera.com/ - **Hiero Solo**: https://github.com/hiero-ledger/solo @@ -1254,4 +1254,4 @@ Remember: 3. Run tests locally before pushing 4. All tests must pass in CI before merging -Thank you for contributing to the Hiero Python SDK! Your tests make the SDK better for everyone. \ No newline at end of file +Thank you for contributing to the Hiero Python SDK! Your tests make the SDK better for everyone. diff --git a/docs/sdk_developers/training/setup/project_structure.md b/docs/sdk_developers/training/setup/project_structure.md index df3353131..5f1e29c9c 100644 --- a/docs/sdk_developers/training/setup/project_structure.md +++ b/docs/sdk_developers/training/setup/project_structure.md @@ -28,7 +28,7 @@ The repository is organized into four main directories: This directory contains all documentation for both users and developers of the SDK. - **`docs/sdk_users/`**: Guides for people *using* the SDK in their applications (e.g., `running_examples.md`). -- **`docs/sdk_developers/`**: Guides for people *contributing* to the SDK (e.g., `CONTRIBUTING.md`, `signing.md`, `testing.md`). +- **`docs/sdk_developers/`**: Guides for people *contributing* to the SDK (e.g., `setup.md`, `workflow.md`, `testing.md`). ### The `examples` Directory @@ -111,4 +111,4 @@ A tool like Pylance (in VS Code) can help verify your import paths and flag any ## Conclusion -This guide outlines the basic file structure of the project. By understanding where different types of code live (`src/`, `tests/`, `examples/`, `docs/`), you can more easily find the classes you need to import and know where to place your new contributions. \ No newline at end of file +This guide outlines the basic file structure of the project. By understanding where different types of code live (`src/`, `tests/`, `examples/`, `docs/`), you can more easily find the classes you need to import and know where to place your new contributions. diff --git a/docs/sdk_developers/training/workflow/07_signing_requirements.md b/docs/sdk_developers/training/workflow/07_signing_requirements.md index f6792cc20..03c02fec8 100644 --- a/docs/sdk_developers/training/workflow/07_signing_requirements.md +++ b/docs/sdk_developers/training/workflow/07_signing_requirements.md @@ -19,4 +19,4 @@ git commit -S -s -m "chore: changelog entry for TokenCreateTransaction" **WARNING** any merge or rebase operations will cause a loss of signing status unless you preserve signing: `git rebase main -S` Read more about signing and how to set up a GPG key at: -[Signing Guide](../../signing.md) +[Signing Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/signing.md) diff --git a/docs/sdk_developers/training/workflow/09_changelog_entry.md b/docs/sdk_developers/training/workflow/09_changelog_entry.md index 6ccedd24a..5e8dd51a8 100644 --- a/docs/sdk_developers/training/workflow/09_changelog_entry.md +++ b/docs/sdk_developers/training/workflow/09_changelog_entry.md @@ -14,4 +14,4 @@ For example: ### Added - Added `.github/workflows/merge-conflict-bot.yml` to automatically detect and notify users of merge conflicts in Pull Requests. -[Read more](../../changelog_entry.md) about creating changelog entries \ No newline at end of file +[Read more](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/changelog-guide.md) about creating changelog entries diff --git a/docs/sdk_developers/workflow.md b/docs/sdk_developers/workflow.md index 9d95c1670..5582984b7 100644 --- a/docs/sdk_developers/workflow.md +++ b/docs/sdk_developers/workflow.md @@ -155,7 +155,7 @@ Lastly, create a branch: git checkout -b my-new-branch-name ``` -Eventually, you'll need to regularly rebase to keep your branch in sync with the upstream repository [Rebase Guide](rebasing.md) +Eventually, you'll need to regularly rebase to keep your branch in sync with the upstream repository [Rebase Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/rebasing.md) ## 5. Commit Your Changes Solve the issue and commit your changes. @@ -195,7 +195,7 @@ For example: git commit -S -s -m "chore: changelog entry for TokenCreateTransaction" ``` -Follow our [Signing Guide](signing.md) with step-by-step instructions. +Follow our [Signing Guide](https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/signing.md) with step-by-step instructions. **WARNING**: using the default commit button on GitHub desktop or VS Studio will result in un-signed commits. diff --git a/docs/maintainers/team.md b/docs/team.md similarity index 100% rename from docs/maintainers/team.md rename to docs/team.md diff --git a/docs/workflows/01-what-are-workflows.md b/docs/workflows/01-what-are-workflows.md deleted file mode 100644 index 650c6ab8b..000000000 --- a/docs/workflows/01-what-are-workflows.md +++ /dev/null @@ -1,69 +0,0 @@ -# 01: What are Workflows? - -Welcome to the Hiero Python SDK! To ensure a smooth, safe, and professional contribution experience, this repository relies heavily on **GitHub Workflows**. This guide explains the foundational concepts of repository automation and how it helps you as a contributor. - -### What is a Workflow? -A workflow is an automated process that is **event-driven**. It stays inactive until a specific "Trigger" occurs. - -* **The Trigger:** This is the **"When"** (e.g., someone comments `/assign` on an issue). -* **The Logic:** This is the **"How"** (e.g., the system checks if you are eligible and then assigns you). - ---- - -## The Anatomy of a Hiero Workflow -Every workflow in this repository follows a standardized design pattern to maintain security and consistency. - -#### 1. Job Title -Every workflow defines one or more **Jobs**. These are the top-level tasks (like `lint`, `test`, or `assign`). You can see these names in the "Actions" tab of the repository to track the progress of your contribution. - -#### 2. Triggers (`on:`) -Workflows are defined by their triggers. Common triggers in this repo include: -* `pull_request`: Runs when you open or update a PR. -* `issue_comment`: Runs when you type a command in an issue. -* `push`: Runs when code is merged into the main branch. - -#### 3. Security Shield (`harden-runner`) -Security is our top priority. We use `step-security/harden-runner` in every workflow. -* **Purpose:** It creates a "secure perimeter" around the temporary computer running the code. It ensures that the workflow only communicates with trusted endpoints (like GitHub) and prevents unauthorized data from leaving the environment. - -#### 4. Workspace Setup (`checkout`) -GitHub starts every workflow on a clean, empty virtual machine. The `actions/checkout` step "downloads" a copy of the Hiero repository onto that machine so the automation can interact with our files. - ---- - -## Why Workflows Call Scripts (Orchestration vs. Logic) -You will notice that our workflow files (YAML) often call external **scripts** located in [`.github/scripts/`](../../.github/scripts). - -* **YAML (The Orchestrator):** Handles the "When." It manages the triggers, the security steps, and the environment setup. -* **Scripts (The Logic):** Handles the "How." We use JavaScript, Python, or Bash scripts for complex decision-making. - -**Why the separation?** Scripts are easier to read, test, and debug. Complex tasks—such as checking if a contributor has completed a "Good First Issue" before assigning them a "Beginner" task—require the advanced logic that only a script can provide. - ---- - -## Why We Rely on Automation -With over 30 workflows running in this repository, automation is the backbone of our "Support Infrastructure." - -| Benefit | Explanation | -| :--- | :--- | -| **Better Developer Experience (DX)** | You get instant feedback. Our Linters find formatting errors in seconds, so you don't have to wait days for a human review. | -| **Safety** | Automation acts as a "Safety Net." Our test suite runs on every PR, ensuring that new changes don't accidentally break existing features. | -| **Scalability** | Automation allows the project to grow. Bots handle the "boring" tasks (like assigning issues or labeling PRs) so maintainers can focus on high-level code architecture. | - ---- - -## Case Study: The Auto-Assignment Bot -A great example of these concepts in action is our **Beginner Assignment Bot**. - -1. **The Trigger:** A contributor types `/assign` on an issue. -2. **The Logic:** The workflow calls `bot-beginner-assign-on-comment.js`. This "brain" checks if the issue is already taken and verifies the contributor's history. -3. **The Result:** If everything is valid, the bot assigns the user immediately. This provides a **seamless DX**—you can start working on an issue at 3 AM without waiting for a maintainer to wake up and manually assign you. - ---- - -## Troubleshooting: Handling Failed Status Checks -If a workflow check fails on your Pull Request: -1. **Don't Panic:** Failures are often simple formatting issues. -2. **Click "Details":** This takes you to the logs. -3. **Find the Error:** The bot will usually point to the exact line of code that needs fixing. -4. **Fix and Push:** Look for the red text in the logs. The bot will usually point to the exact file and line number that needs fixing. diff --git a/docs/workflows/02-architecture.md b/docs/workflows/02-architecture.md deleted file mode 100644 index 0ae244be0..000000000 --- a/docs/workflows/02-architecture.md +++ /dev/null @@ -1,101 +0,0 @@ -# 02: How Workflows Are Structured (Orchestration + Logic) - -Building on the basics from [01-what-are-workflows.md](./01-what-are-workflows.md), this document explains **exactly how** we structure workflows in the Hiero Python SDK repository. - -We use a very deliberate pattern called **Orchestration vs. Logic separation**. -This makes it much easier for you (and future contributors) to **create**, **tweak**, **understand**, and **maintain** automations. - -## The Simple Flow - -1. Something happens on GitHub - (someone comments `/assign`, a PR is opened, code is pushed…) - -2. ↓ - -3. The **workflow (.yml)** wakes up and quickly decides: - “Should this run right now?” - (based on event type, branch, labels, etc.) - -4. ↓ - -5. If yes → it calls the matching **script (.js)** - -6. ↓ - -7. The **script** does all the real work - (reads details, thinks, decides, talks to GitHub, writes comments…) - -8. ↓ - -9. Results show up in GitHub - (comment posted, label added, check passed/failed, log messages…) - -## Two Folders – Two Very Different Jobs - -| Folder | File type | Role | Contains mostly… | Thinking allowed? | -|-------------------------------|---------------|-------------------|--------------------------------------------------|-------------------| -| `.github/workflows/` | `*.yml` | **Orchestration** | When to run, permissions, setup, calling script | Almost none | -| `.github/scripts/` | `*.js` (main) | **Business Logic**| Decisions, API calls, calculations, comments | All of it | - -**Golden rule used by the maintainers:** - -> If it involves **thinking**, **deciding**, **checking conditions**, **calling APIs**, **handling errors**, or **writing messages to users** → put it in a **script**.
-> If it is only about **starting the process**, **setting security**, or **connecting things** → put it in the **workflow YAML**. - -## What Each Layer Is Responsible For - -### Workflows (.github/workflows/*.yml) – Orchestration - -Responsible for: - -- Defining **triggers** (`on: pull_request`, `on: issue_comment`, etc.) -- Setting **permissions** (`permissions: { issues: write }`) -- Selecting **runners** (`runs-on: ubuntu-latest`) -- Controlling **concurrency** (prevent duplicate runs) -- Wiring **inputs**, **environment variables**, **secrets** -- Calling the script (usually via `actions/github-script`) - -Should contain **almost zero decision-making logic**. -Complex `if:` conditions, string parsing, API calls, etc. do **not** belong here. - -### Scripts (.github/scripts/*.js) – Business Logic - -Responsible for: - -- Interpreting the **event payload** (`context.payload`) -- Making **decisions** (“Is this a valid /assign?”, “Does the issue have the right label?”) -- Calling **GitHub APIs** (`github.rest.issues.addLabels`, `createComment`, …) -- Computing **results** -- Handling **errors** (`try/catch`, `core.setFailed`) -- Producing **logs** (`core.info`, `core.warning`) -- Generating **user-facing comments** (helpful messages, emojis, instructions) - -**If it involves thinking → it belongs in the script.** - -## Naming Convention (Very Important!) - -We deliberately name workflows and their scripts **very similarly** so you can instantly see which files belong together: - -Examples from the repository: - -- `.github/workflows/bot-gfi-assign-on-comment.yml` - → `.github/scripts/bot-gfi-assign-on-comment.js` - -This makes scanning `.github/` much faster when you want to understand or fix something. - -## Best Practices Summary - -- **Workflows** should have a **good, descriptive title** - (the `name:` field – it appears in the Actions tab and in PR checks) - Good: `Beginner Issues – Auto-assign when /assign is commented` - Bad: `assign` - -- **Scripts** should be **well documented**: - - Start with a comment block explaining **purpose** - - Add inline comments for any non-obvious logic - - Example: - ```js - // Purpose: Assigns a good-first-issue only if it's still free and correctly labeled - // Allowed only via /assign command in issue comments - ``` - \ No newline at end of file diff --git a/docs/workflows/03-workflow-best-practices.md b/docs/workflows/03-workflow-best-practices.md deleted file mode 100644 index 970134e65..000000000 --- a/docs/workflows/03-workflow-best-practices.md +++ /dev/null @@ -1,475 +0,0 @@ -# 03: Workflow Best Practices - -Building on the concepts from [01-what-are-workflows.md](./01-what-are-workflows.md) and -[02-architecture.md](./02-architecture.md), this guide establishes best practices for -writing and maintaining GitHub Actions workflows and their companion scripts. - -## Why Best Practices Matter - -Automation is powerful — but power demands discipline. Unlike application code, -workflow bugs can: - -- Mass-assign or unassign contributors -- Spam dozens of users with incorrect comments -- Leak permissions or secrets -- Create irreversible state changes -- Break the entire contributor experience - -A single mistake can create hours of cleanup. These best practices exist to ensure -our workflows are **safe**, **predictable**, **debuggable**, and **maintainable at -scale**. - ---- - -## 1. Separate the Workflow from the Logic - -As explained in [02-architecture.md](./02-architecture.md), we follow the -**Orchestration vs. Logic** pattern: - -| Layer | Folder | Responsibility | -| :--- | :--- | :--- | -| **Workflow** (`.yml`) | `.github/workflows/` | Triggers, permissions, env setup, calling scripts | -| **Script** (`.js`/`.sh`) | `.github/scripts/` | Decisions, API calls, error handling, comments | - -Avoid adding logic directly to the workflow YAML. Inline logic is brittle — -formatting is harder, some variables can become malformed, and it is difficult to -test. - -### ❌ Bad: Logic in YAML - -```yaml -- run: | - ASSIGNEES=$(gh api /repos/$REPO/issues/$NUM/assignees | jq -r '.[].login') - if [ -z "$ASSIGNEES" ]; then - gh issue assign $NUM --assignee $USER - fi -``` - -### ✅ Good: Logic in a script - -```yaml -- uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 - with: - script: | - const script = require('./.github/scripts/bot-assign.js'); - await script({ github, context, core }); -``` - ---- - -## 2. Avoid Hardcoding — Use Environment Variables - -When adding values to workflows or scripts, extract them as variables rather than -hardcoding. Ideally, environment variables should be **defined in the workflow YAML -and passed to the script**. - -### ❌ Bad: Hardcoded in the script - -```javascript -if (team === '@hiero-ledger/core-maintainers') { - // ... -} -``` - -### ✅ Good: Passed from the workflow - -**Workflow YAML:** - -```yaml -env: - MAINTAINER_TEAM: '@hiero-ledger/core-maintainers' - MAX_ASSIGNEES: '3' - INACTIVITY_DAYS: '21' -``` - -**Script:** - -```javascript -const TEAM = process.env.MAINTAINER_TEAM; -const MAX = parseInt(process.env.MAX_ASSIGNEES, 10); - -if (team === TEAM) { - // ... -} -``` - -This improves maintainability (one place to change a value) and security (secrets -stay in the workflow layer). - ---- - -## 3. Secrets Handling - -Secrets are the most sensitive part of any workflow. Follow these rules strictly: - -| Rule | Why | -| :--- | :--- | -| **Never log secrets** | Even partial logging can expose tokens | -| **Never transform secrets** | String operations on secrets can leak them via error messages | -| **Never pass secrets unless required** | Minimize the blast radius of a compromise | -| **Use `${{ secrets.NAME }}`** | Always reference secrets through GitHub's secrets mechanism | - -### ❌ Bad - -```yaml -- run: echo "Token is ${{ secrets.GITHUB_TOKEN }}" -- run: | - TOKEN="${{ secrets.MY_TOKEN }}" - TRIMMED=${TOKEN:0:10} # Transformation can leak -``` - -### ✅ Good - -```yaml -steps: - - run: gh api /repos/... # gh CLI reads GITHUB_TOKEN from env - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} -``` - ---- - -## 4. Permissions — Default to Read, Escalate Only When Required - -Every workflow must explicitly declare permissions, scoped to the **minimum** -required. - -```yaml -permissions: - issues: write # Only if the workflow posts comments or edits issues - contents: read # Default — read-only access to repo contents - pull-requests: read # Only escalate to write if modifying PRs -``` - -**Never** give a workflow excessive permissions or token access. If a workflow only -reads data, it should **not** have write access. - -For more on securing workflows, see -[how-to-pin-github-actions.md](../sdk_developers/how-to-pin-github-actions.md). - ---- - -## 5. Log for Debugging and Maintainability - -A workflow should not just work — it should be **easy to scale and debug**. If a -maintainer cannot diagnose a failure from logs, the workflow is incomplete. - -### What to Log - -Logs should show: - -- What triggered execution -- What decisions were made -- Why branches were taken -- What API calls occurred -- Why exits happened - -### Use Structured, Prefixed Logs - -Every log line should identify the source and describe exactly what happened. - -#### ❌ Bad - -```javascript -console.log('assigned'); -console.log('done'); -``` - -#### ✅ Good - -```javascript -console.log('[assign-bot] Issue #42 already assigned:', assignees); -console.log('[assign-bot] Exit: user has not completed a Good First Issue'); -console.log('[assign-bot] Assigned user @alice to issue #42'); -``` - -### Always Log Exits - -Include logs even when exiting early, so you know why the workflow stopped and what -conditions caused it: - -```javascript -if (!commentRequestsAssignment(body)) { - console.log('[assign-bot] Exit: not an /assign request'); - return; -} -``` - -### What is Acceptable to Log - -| ✅ Safe to log | ❌ Never log | -| :--- | :--- | -| Issue numbers | Tokens or secrets | -| Usernames | API keys | -| Label names | Private user data | -| Counts and IDs | Full event payloads | - ---- - -## 6. Error Handling - -Automation must fail **predictably** and **helpfully**. Errors fall into three -categories: - -### a) Expected Failures - -The user did not meet conditions (e.g., eligibility requirements). These often -warrant a helpful comment. - -```javascript -if (!hasCompletedGFI) { - await postComment( - `Sorry @${user}, we were unable to assign you. ` + - `You must first complete a Good First Issue.` - ); - return; -} -``` - -### b) Operational Failures - -The GitHub API malfunctioned or something unexpected happened. Log the error and -optionally notify the user. - -```javascript -try { - await github.rest.issues.addAssignees({ owner, repo, issue_number, assignees }); -} catch (error) { - console.error('[assign-bot] API error:', error.message); - // Optionally comment to the user -} -``` - -### c) System Failures - -When the workflow cannot safely proceed, tag maintainers for assistance: - -```javascript -await postComment( - `Sorry @${user}, we were unable to assign you due to a technical issue. ` + - `Requesting @hiero-ledger/maintainers assistance.` -); -core.setFailed('System failure: ' + error.message); -``` - -**Never exit without logging the exit reason.** Every `return` should have a -corresponding log line so unexpected behavior can be debugged. - ---- - -## 7. Notify Users - -### When to Notify - -Notify the user when: - -- They attempted an action (e.g., `/assign`) -- Eligibility checks failed -- Prerequisites are missing -- They are waiting for a result - -Scripts should generate an **informative comment** and post it. Silent failures -leave contributors confused. - -### When to Tag Maintainers - -Tag maintainers (`@hiero-ledger/maintainers`) when automation cannot safely decide: - -- API unavailable or returning unexpected responses -- Ambiguous labels or state -- Permission failures -- Edge cases the script was not designed to handle - ---- - -## 8. Safety Rules - -### Pin Action Versions - -All third-party actions must be pinned to a **full commit SHA**, not a floating tag. - -```yaml -# ❌ Bad — floating tag -uses: actions/checkout@v4 - -# ✅ Good — pinned SHA with version comment -uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 -``` - -See [how-to-pin-github-actions.md](../sdk_developers/how-to-pin-github-actions.md) -for the full step-by-step guide. - -### Treat All User Input as Untrusted - -Anything coming from issue titles, comments, labels, PR bodies, or usernames should -be validated before use. - -#### ❌ Bad - -```javascript -body.includes('/assign'); -``` - -#### ✅ Good - -```javascript -/^\s*\/assign\s*$/i.test(body); - -function isSafeSearchToken(value) { - return /^[a-zA-Z0-9._/-]+$/.test(value); -} -``` - -### Watch Out with Destructive Actions - -Before performing destructive actions (deleting labels, unassigning users, closing -issues), confirm: - -- Correct issue / PR -- Correct state (labels, assignees) -- Not already done (idempotency) - -### Avoid `pull_request_target` with Untrusted Code - -`pull_request_target` runs with **write permissions on the base repository**, even -for PRs from forks. Never check out or execute code from the fork branch inside -a `pull_request_target` workflow — this allows a contributor to run arbitrary -code with your repository's write token. - -```yaml -# ❌ Dangerous — executes fork code with write token -on: pull_request_target -steps: - - uses: actions/checkout@... - with: - ref: ${{ github.event.pull_request.head.sha }} # attacker-controlled - - run: npm install && npm test # runs attacker code -``` - -If you must use `pull_request_target` (e.g., to post comments on fork PRs), -keep the workflow free of any checkout or execution of PR code, and scope -permissions to the minimum required. - ---- - -## 9. Concurrency - -Workflows might be triggered multiple times simultaneously. Use concurrency controls -to prevent race conditions: - -```yaml -concurrency: - group: assign-${{ github.event.issue.number }} - cancel-in-progress: false -``` - -Use `cancel-in-progress: false` for workflows that mutate state (assigning users, -posting comments) to avoid partial execution. Use `cancel-in-progress: true` for -read-only checks (linting, testing) where only the latest run matters. - ---- - -## 10. Testing and Dry Runs - -No workflow change is considered safe without testing. Because workflow bugs can -mass-edit issues, spam contributors, or leak permissions, **maintainers expect proof -of testing in PRs**. - -### Fork Testing (Strongly Recommended) - -Use your personal fork to validate behavior safely. You can trigger events, create -test issues, simulate comments, and inspect logs without risk to the main repository. - -See [testing_forks.md](../sdk_developers/training/testing_forks.md) for the full -fork testing guide. - -**Checklist:** - -- [ ] Does the workflow trigger correctly? -- [ ] Have I tested various edge cases? -- [ ] Are comments formatted correctly? -- [ ] Are logs clear and informative? - -### Dry-Run Techniques - -Dry runs let you verify logic without performing real mutations. They divert actions -to log instead of execute. - -**Workflow YAML:** - -```yaml -on: - workflow_dispatch: - inputs: - dry_run: - description: 'Run in dry-run mode' - type: boolean - default: true - -env: - DRY_RUN: ${{ github.event.inputs.dry_run }} -``` - -**Script:** - -```javascript -if (process.env.DRY_RUN === 'true') { - console.log('[dry-run] Would assign:', username); - return; -} - -await github.rest.issues.addAssignees({ owner, repo, issue_number, assignees: [username] }); -``` - -If dry-run is used, it should be: - -- **Clear** — obvious from logs that it is active -- **Well-logged** — every skipped mutation should be logged -- **Default to true** on `workflow_dispatch` -- **Easy to maintain** — simple toggle, not complex branching - -### Local Testing - -Large parts of behavior can be validated locally without pushing commits: - -1. Simulate the GitHub event payload (or extract from a real event) -2. Call your script directly and observe output -3. Verify decision-making, formatting, and branching - -**What local testing cannot prove:** - -| Cannot validate locally | Requires fork testing | -| :--- | :--- | -| GitHub permissions | ✅ | -| Actual API authorization | ✅ | -| Concurrency behavior | ✅ | -| Runner environment | ✅ | - ---- - -## Quick Reference Checklist - -Use this checklist when writing or reviewing a workflow: - -| # | Practice | Check | -| :--- | :--- | :--- | -| 1 | Logic is in scripts, not YAML | ☐ | -| 2 | Values use env vars, not hardcoded | ☐ | -| 3 | Secrets are never logged or transformed | ☐ | -| 4 | Permissions are explicit and minimal | ☐ | -| 5 | Logs are structured, prefixed, and informative | ☐ | -| 6 | Errors are handled at all three levels | ☐ | -| 7 | Users are notified on failures | ☐ | -| 8 | Actions are SHA-pinned, inputs are validated | ☐ | -| 9 | Concurrency groups prevent race conditions | ☐ | -| 10 | Tested on a fork with proof in the PR | ☐ | - ---- - -## Related Documentation - -- [01: What are Workflows?](./01-what-are-workflows.md) -- [02: How Workflows Are Structured](./02-architecture.md) -- [How to Pin GitHub Actions](../sdk_developers/how-to-pin-github-actions.md) -- [Testing with Forks](../sdk_developers/training/testing_forks.md) -- [Developer PR Checklist](../sdk_developers/checklist.md)