# Contributing

Thanks for wanting to help with OmniWM.

Bug fixes, documentation improvements, performance work, focused cleanups, features, and thoughtful ideas are all welcome.

## What Makes a Good Contribution

- Fix bugs or regressions
- Improve documentation or onboarding
- Add useful features or workflow improvements
- Improve performance or reduce latency
- Clean up code when it clearly improves maintainability
- Share demos, examples, or tutorials

## Project Direction

- Refactors are fine when they solve a real problem, but they should come with a detailed reason. Explain what is not working well today, why the refactor is needed, and what it improves.
- Please keep contributions in Swift so the codebase stays cohesive.

## Before Opening a Pull Request

- For larger changes, open an issue or start a discussion first so we can align on direction.
- Keep changes focused. Smaller, well-explained pull requests are much easier to review and merge.
- If your change affects behavior, config, docs, or CLI output, call that out clearly in the pull request description.

## Pull Request Expectations

- Explain the problem you are solving and why this approach makes sense.
- Include verification notes **if possible**. Mention what you ran, checked, or verified.
- Add screenshots, recordings, or CLI examples when they help explain the change.
- Update documentation when behavior, workflows, or interfaces change.

## Trace Files

Include a trace file when possible, especially with bug reports. It records OmniWM activity and state around the problem. Open **Settings → Troubleshooting**, click **Start Recording**, reproduce the bug, then click **Stop & Save Recording** and attach the saved `.log` file.

## Basic Workflow

1. Fork the repository.
2. Create a branch for your change.
3. Make the change and verify it.
4. Open a pull request with clear context and reasoning.

## Improving the AI Issue-Report Prompt

The prompt that rewrites bug reports into GitHub issues lives in plain Markdown, so you can improve it without editing Swift. See [docs/issue-report-prompt.md](docs/issue-report-prompt.md) for the files to edit, the constraints to preserve, and how to test.

## Questions and Ideas

If you are unsure about something, open an issue or ask in the pull request. Thoughtful questions are always welcome.

Thanks again for helping improve OmniWM.