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

> Learn how to report a bug in OpenWork using GitHub Issues. Follow our guide to include reproduction steps, expected behavior, and logs for faster resolution.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: how-to-guide
- Published: 2026-08-04

---

**Open a GitHub Issue using the Bug report template in [`.github/ISSUE_TEMPLATE/bug.yml`](https://github.com/different-ai/openwork/blob/main/.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`](https://github.com/different-ai/openwork/blob/main/.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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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.

```markdown
**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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/.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`](https://github.com/different-ai/openwork/blob/main/SUPPORT.md) for complete pre-submission guidance
- Maintainers triage using [`TRIAGE.md`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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.