# Contributing
Thanks for helping out! Before you get started, here are a few guidelines to follow:

## Issue Guidelines
### Basic Information
When you file an issue, please provide the following information:
- Operating system
- Rust version (if you built it yourself)
- Hummingbird commit hash
  - You can find this by clicking the "Hummingbird" in the top left on Windows or Linux, or by going to the "Hummingbird" menu in macOS and selecting "About Hummingbird". It's next to the version number.
- Hardware information
  - CPU model
  - RAM size
  - Disk type and size
  - Graphics card model (including integrated)

### Reproducability
When reporting an issue, please provide minimal steps that reproduce the issue. **If reproducing your issue requires distributing copyrighted material, please *DO NOT* attach this material to your issue.** Create the issue first, then we can establish further steps.

## PR Guidelines
### Code Style
Try not to introduce any warnings (including clippy lints). Dead code warnings are acceptable, if there is a reasonable possibility the dead code would be required in the near future. Ensure your code has been formatted correctly before submitting - you can do this with `cargo fmt`.

### Documentation
If you introduce a new component that has a lot of moving pieces, or will be a critical part of the application, make sure it's well documented. For example, consider the Device traits (in `src/devices/traits.rs`). Since this code is likely to interact with other components, and the code is likely to be used by other people, it's important to document it well.

Note that not all code in Hummingbird is documented this extensively. If you think your code is self-explanatory (i.e. commenting it would essentially result in simply explaining that the line of code performs the action that it self-evidently peforms anyways), don't over-comment it. Instead, focus on writing clear and concise code that is easy to understand. However, if you do something that might have more opaque reasoning or flow, consider adding a comment to explain it.

### Platform Support
It is expected that new code works on all three major platforms (Linux, macOS, and Windows). However, while you should test on all platforms available to you, I am aware that not everyone has the hardware (or time) to do this.

If you think it's likely that your code will not work on a particular platform, please reach out to me (@143mailliw) when opening your pull request. I can fill in the gaps.

### Generative AI usage
The use of large language models (LLMs) is acceptable **if and only if** a thorough manual review is performed. **By submitting a pull request, you are guaranteeing the following:**
- You have *personally* reviewed all generated code to make sure that it will not cause undue technical issues, including testing for edge cases, ensuring data integrity, and verifying that performance standards are maintained.
- You have ensured that Hummingbird's UX standards are not meaningfully degraded by this change.
- You have ensured that any changes to the user interface are in keeping with the design of the rest of the app, or have provided good reason to change them.
- You fully understand the content of the pull request and are prepared to explain it.
- You have verified that the change does not reduce overall code quality or maintainability.
- You own the rights to all content provided, or the license or attribution from the licensed content is properly included.

The following rules additionally apply to contributions made in whole or part using generative AI:
- The use of generative AI is clearly disclosed with one or more of the following:
  - Co-authored tag on relevant commits (eg. `Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>` in the commit description, as generated by Claude Code)
  - "This PR was created with assistance from \<model>." at the beginning or end of the pull request's description.
- All submitted text is in English. We do not have the capacity to review text or translations for other languages at this time and we do not trust LLMs to handle this correctly.
- No AI-generated images, icons, SVG files, or other critically artistic works are included in the content of the pull request.

Pull requests determined by maintainers not to follow these guidelines will be rejected. Repeat offenders may be blocked from contributing.