How to Report a Bug in OpenWork: A Complete Guide to GitHub Issues

Report bugs in OpenWork by opening a GitHub Issue using the Bug report template, which requires specific sections like Summary, Steps to Reproduce, and Expected vs Actual behavior.

The OpenWork repository (different-ai/openwork) uses structured GitHub Issues to track defects. When you encounter unexpected behavior, the project provides standardized templates and documentation to ensure maintainers can quickly reproduce and resolve your issue.

Using the Bug Report Template

OpenWork enforces a structured format for all bug reports through the Bug report template. This template is defined in .github/ISSUE_TEMPLATE/bug.yml and automatically populates the issue form with required fields when you select it from the GitHub web interface.

Required Fields

Every bug report must include these core sections to be actionable:

• Summary – A concise description of what is malfunctioning
• To Reproduce – Numbered steps that consistently trigger the bug
• Expected behavior – What you anticipated should happen
• Actual behavior – What actually occurred, including error messages

Optional Diagnostic Information

The template also collects optional metadata that accelerates triage:

• OpenWork version – The specific release or commit hash (e.g., 0.1.166)
• Operating system – Your OS and version (e.g., macOS 14.2)
• Screenshots or recordings – Visual evidence of the defect
• Additional context – Any other relevant configuration details

Step-by-Step Bug Reporting Workflow

According to the project's SUPPORT.md file, follow this standardized process to ensure your report reaches the triage queue efficiently:

1. Search existing issues – Verify the bug hasn't already been reported to avoid duplicates.
2. Open a new issue – Navigate to the Issues tab and select the Bug report template.
3. Fill out required sections – Complete the Summary, To Reproduce, Expected behavior, and Actual behavior fields with precise details.
4. Add optional data – Include your OpenWork version, OS details, screenshots, and any environment-specific context.
5. Submit – The issue will be automatically labeled bug and added to the maintainers' triage queue.

Creating Bug Reports Programmatically

You can generate bug reports from the command line using the GitHub CLI (gh). This approach allows you to draft the report locally using the standard template structure before submitting.

Create a temporary markdown file with the required sections:

cat <<'EOF' > bug_report.md

### Summary

<!-- What is not working? -->

### To Reproduce

1. <!-- Step 1 -->
2. <!-- Step 2 -->
3. <!-- Step 3 -->

### Expected behavior

<!-- What you expected to happen -->

### Actual behavior

<!-- What actually happened -->

### Desktop info (optional)

- OpenWork version: 0.1.166
- OS: macOS 14.2
EOF

Submit the issue using the gh command with the bug label:

gh issue create \
  --title "[Bug]: Brief description of the problem" \
  --body-file bug_report.md \
  --label bug

Key Files for Bug Reporting

Two files in the repository define the bug reporting standards:

• .github/ISSUE_TEMPLATE/bug.yml – Defines the structured form fields and automatic labeling logic used for every new bug issue.
• SUPPORT.md – Contains high-level guidance on where to seek help and detailed instructions for submitting effective bug reports.

Summary

• OpenWork tracks defects exclusively through GitHub Issues using a standardized template defined in .github/ISSUE_TEMPLATE/bug.yml.
• Every bug report requires four essential sections: Summary, Steps to Reproduce, Expected behavior, and Actual behavior.
• The SUPPORT.md file documents the complete workflow, which includes searching existing issues, selecting the correct template, and providing diagnostic metadata.
• Issues created via the template are automatically labeled bug and routed to the triage queue.
• You can submit reports programmatically using the gh CLI with a markdown file structured according to the template requirements.

Frequently Asked Questions

What information is mandatory when reporting a bug in OpenWork?

You must provide a Summary of the problem, specific Steps to Reproduce, the Expected behavior, and the Actual behavior observed. These four fields are required in the .github/ISSUE_TEMPLATE/bug.yml template and ensure maintainers can replicate the issue.

How do I avoid creating duplicate bug reports?

Search the existing Issues tab in the different-ai/openwork repository using keywords related to your problem. The SUPPORT.md file explicitly lists this as the first step in the bug reporting workflow to prevent redundant tickets.

Can I report a bug without using the web interface?

Yes. You can use the GitHub CLI (gh) to create issues from the command line. Create a markdown file containing the required sections (Summary, To Reproduce, Expected behavior, Actual behavior) and run gh issue create --body-file yourfile.md --label bug.

Where are the bug report templates stored?

The structured bug report template lives in .github/ISSUE_TEMPLATE/bug.yml within the repository root. This file defines the form fields, required inputs, and automatic labeling that appears when you select "Bug report" from the New Issue menu.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}