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

Open a GitHub Issue using the Bug report template in .github/ISSUE_TEMPLATE/bug.yml and include steps to reproduce, expected vs. actual behavior, environment details, and debug logs.

OpenWork is an open-source productivity platform developed by different-ai. When you encounter unexpected crashes, UI glitches, or functional errors, submitting a well-structured bug report helps maintainers reproduce and fix the problem efficiently. This guide explains exactly how to report a bug in OpenWork using the repository's standardized GitHub Issues workflow.

Where Bug Reports Are Tracked

OpenWork uses GitHub Issues as its sole bug-tracking system. The repository provides a dedicated bug-report template that enforces consistent information collection.

The template lives at .github/ISSUE_TEMPLATE/bug.yml and prompts you for:

• A concise summary
• Steps to reproduce
• Expected behavior
• Actual behavior
• Screenshots or videos
• Version and OS details

Supplementary guidance appears in SUPPORT.md, which explains how to gather debug artifacts for desktop-related issues.

Step-by-Step Bug Reporting Process

1. Initiate a New Issue

Navigate to the OpenWork repository and click Issues → New issue. Select the Bug report template from the list. This automatically formats your submission with required fields and applies the bug label upon submission.

2. Fill Out Required Fields

The bug.yml template mandates four core sections:

Field	Purpose	Tips
Summary	One-line description of the defect	Be specific: "Crash on workspace load with 500+ plugins" beats "App broken"
To Reproduce	Numbered steps that reliably trigger the bug	Start from a fresh app launch; include exact menu paths
Expected behavior	What you anticipated	Describe the correct outcome without referencing the bug
Actual behavior	What occurred instead	Include exact error messages, stack traces, or visual symptoms

3. Attach Supporting Evidence

Visual documentation accelerates diagnosis. Add:

• Screenshots of error dialogs or UI corruption
• Screen recordings for interaction bugs
• Debug exports for desktop-specific issues (see below)

4. Provide Environment Details

Collect these from Settings → General in OpenWork:

• OpenWork version (e.g., 0.1.202)
• Operating system and version (e.g., macOS Sonoma 14.2, Windows 11 23H2)

5. Submit and Monitor

Click Submit new issue. Maintainers apply triage labels according to the internal TRIAGE.md rubric and may request additional diagnostics. Respond promptly to clarification requests to prevent automatic closure due to inactivity.

How to Collect Debug Logs for Desktop Bugs

Desktop-specific issues require additional artifacts. According to SUPPORT.md, generate these files:

Settings → Debug contains two export options:

• Runtime debug report — system state snapshot
• Developer log — detailed execution trace

Download both files and attach them to your GitHub Issue. These logs contain stack traces and component initialization records that pinpoint failure points.

**Summary**
The app crashes when opening a workspace that contains more than 500 plugins.

**To Reproduce**
1. Open OpenWork.
2. Click **File → Open Workspace**.
3. Select a workspace that has 600 plugins installed.
4. The application freezes and then shows a "Unexpected error" dialog.

**Expected behavior**
The workspace should load normally, showing all plugins in the sidebar.

**Actual behavior**
The app freezes for ~30 seconds, then crashes with the error:
`Error: Failed to load plugin manifest (code 500)`

**Screenshots**
![Crash dialog](https://github.com/user/repo/assets/12345678/bug-screenshot.png)

**OW version & Desktop info (optional)**
- OpenWork version: 0.1.202
- OS: macOS Sonoma 14.2

**Additional context**
The issue only occurs on macOS; Windows 11 works fine with the same workspace.

This example demonstrates proper formatting: numbered reproduction steps, exact error strings, version specificity, and cross-platform context that helps isolate environment-specific bugs.

What Happens After Submission

The OpenWork maintainers use TRIAGE.md to categorize incoming issues. Your report progresses through these stages:

1. Labeling — bug label applied automatically; additional labels (high-priority, desktop, needs-info) added manually
2. Reproduction — maintainers attempt to replicate using your steps
3. Assignment — confirmed bugs route to relevant component owners
4. Resolution — fix merged, issue closed with reference to the pull request

Incomplete reports risk the needs-info label or closure after 30 days of inactivity. Following the template minimizes back-and-forth and accelerates fixes.

Bug Report Best Practices

Reproducibility is paramount. A bug that cannot be triggered consistently stalls investigation. Before submitting:

• Test on a clean OpenWork installation
• Disable plugins to isolate conflicts
• Confirm the issue persists after restarting the application

Search existing issues first. Duplicate reports fragment discussion and slow triage. Use GitHub's search with keywords from your error message.

One bug per issue. Compound reports containing multiple unrelated problems require tedious separation and delay resolution.

Summary

• OpenWork bug reports use the GitHub Issues system with a structured template at .github/ISSUE_TEMPLATE/bug.yml
• Required fields include summary, reproduction steps, expected/actual behavior, and environment details
• Desktop bugs need debug exports from Settings → Debug (runtime report and developer log)
• Reference SUPPORT.md for complete pre-submission guidance
• Maintainers triage using TRIAGE.md; complete reports receive faster resolution

Frequently Asked Questions

What if the bug report template doesn't appear?

Ensure you're creating the issue in the correct repository (different-ai/openwork). The template only renders for issues opened directly in this repository, not forks or mirrored copies. If templates are missing, verify your GitHub account has Issue creation permissions and try a hard refresh.

Can I report security vulnerabilities through GitHub Issues?

No. Security-sensitive bugs bypass the public Issues system. Check SECURITY.md in the repository root for responsible disclosure instructions—typically an encrypted email address or private security advisory form. Public disclosure risks exploitation before patches deploy.

How do I report a bug in an older OpenWork version?

Update to the latest release first. The SUPPORT.md documentation explicitly states that maintainers only investigate bugs reproducible on current versions. If the bug persists after updating, include both the original and current version numbers in your report to establish the regression timeline.

What response time should I expect?

OpenWork maintains no formal SLA, but active bugs typically receive triage labels within 3–5 business days. Complex issues requiring deep investigation may take longer. Add a constructive comment with new findings if the issue stalls—this bumps it without creating noise. Avoid "bump" comments without substantive additions.

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