diff --git a/AI.md b/AI.md new file mode 100644 index 0000000..7eb2a5d --- /dev/null +++ b/AI.md @@ -0,0 +1,19 @@ +# AI-assisted development + +FancyWin was vibe coded with the assistance of a large language model. The +application has been reviewed and tested for its primary use case, but that does +not guarantee that every code path, Windows configuration, application, monitor +arrangement, or edge case is free from defects. + +Like any software, particularly an independently developed utility that +interacts directly with desktop windows, FancyWin should be evaluated carefully +before relying on it. You use the application entirely at your own risk. The +authors and contributors accept no responsibility for data loss, disruption, +unexpected window behaviour, or any other damage arising from its use. + +AI-assisted development is stated here openly so that you can make an informed +choice. If you are not comfortable using software created with AI assistance, +that is entirely reasonable—FancyWin is simply not the application for you, and +you should not use it. + +Bug reports, careful testing, and constructive contributions are welcome. diff --git a/CONTRIBUTION.md b/CONTRIBUTION.md new file mode 100644 index 0000000..8e3f787 --- /dev/null +++ b/CONTRIBUTION.md @@ -0,0 +1,106 @@ +# 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.