Steve Cliff
107 lines
4.5 KiB
Markdown
107 lines
4.5 KiB
Markdown
# 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.
|