# Contributing to FancyWin

Thank you for considering a contribution to FancyWin. Bug reports, focused
feature proposals, documentation improvements, testing, and code contributions
are all welcome.

Please remember that FancyWin interacts directly with desktop windows through
the Windows API. Changes that appear small can behave differently across
applications, monitor arrangements, DPI settings, and Windows integrity levels.

## Before contributing

- Search the existing issues and pull requests before opening a duplicate.
- Keep proposals focused on FancyWin's purpose as a lightweight, portable
  window-zone manager.
- For a substantial feature or architectural change, open an issue first so the
  approach can be discussed before significant work begins.
- Read [AI.md](AI.md) for the project's AI-assisted development disclosure.

## Reporting a bug

Include enough information for another person to reproduce the problem:

- FancyWin version and whether the official release or a source build was used
- Windows 11 version and system architecture
- Monitor count, arrangement, resolution, and DPI scaling
- The affected application's name and whether it was running as administrator
- The relevant YAML configuration, with any sensitive information removed
- Exact steps to reproduce the behaviour
- Expected and actual behaviour
- Output from `fancywin.exe --debug`, where relevant

Do not include credentials, private paths, or other sensitive data in logs or
configuration examples.

## Suggesting a feature

Describe the use case before proposing an implementation. Explain what problem
the feature solves, how a user would configure or operate it, and any expected
interaction with existing layouts, hotkeys, overlays, or tray behaviour.

FancyWin aims to remain portable and self-contained. Features that require an
installer, service, driver, administrator access, or a large runtime dependency
need especially strong justification.

## Development workflow

1. Fork the repository and create a branch for one focused change.
2. Make the change and add or update tests where practical.
3. Run `make build` from the repository root.
4. Test Windows-specific behaviour on Windows 11 when the change affects the
   platform backend, tray icon, overlay, hotkeys, or window movement.
5. Update `README.md`, `BUILD.md`, and the example YAML when user-visible
   behaviour or configuration changes.
6. Commit with a concise message that explains the purpose of the change.
7. Open a pull request describing the change and how it was verified.

Detailed build commands, architecture notes, and the Windows smoke-test
checklist are available in [BUILD.md](BUILD.md).

## Code expectations

- Keep the project buildable as a single portable Go executable with
  `CGO_ENABLED=0`.
- Format Go code with `gofmt`.
- Prefer standard-library functionality and the existing dependencies. Discuss
  new dependencies before adding them.
- Keep platform-neutral configuration and geometry logic separate from Win32
  implementation details.
- Check every Windows API result for meaningful failure where possible and
  release native resources deterministically.
- Preserve existing YAML compatibility unless a deliberate format-version
  change has been agreed.
- Add tests for validation, geometry, parsing, and other platform-neutral logic.
- Avoid unrelated formatting or refactoring in a focused pull request.

## Pull requests

A good pull request:

- Addresses one coherent problem
- Links the relevant issue, if one exists
- Explains important implementation choices and trade-offs
- Lists the commands and Windows scenarios used for verification
- Includes screenshots for visible overlay or tray changes
- Calls out compatibility changes, limitations, and remaining risks
- Does not contain generated binaries or unrelated files

Maintainers may ask for changes or decline work that does not fit the project's
scope. Review comments are about improving the contribution and keeping the
application dependable for its users.

## Security and elevated applications

Do not publish a security vulnerability as a public issue. Contact the
repository owner privately with a clear description, reproduction steps, and
the potential impact.

FancyWin is intended to work without administrator privileges. Windows normally
prevents a standard-integrity process from manipulating elevated windows; do
not bypass that boundary or introduce privilege escalation mechanisms.

## Conduct

Be respectful, constructive, and patient when discussing issues and reviewing
the work of others.