heads/CONTRIBUTING.md

# Contributing to LinuxBoot/Heads

Thank you for your interest in contributing to LinuxBoot/Heads! We welcome contributions
from everyone. Following these contribution guidelines will make handling of issues and
PRs a faster and smoother process, so please try to adhere to them.

## Communication Channels

For the most up-to-date information on our community channels, please visit:
https://osresearch.net/community/

## Best Practices for Issues and Contributions

Before opening an issue or submitting a contribution, please:

1. Search existing resources (GitHub issues, wiki, Matrix channel history).
2. Review the documentation at https://osresearch.net.
3. Choose the appropriate channel for your contribution or question.

If you're unsure about what kind of issue you're looking at or whether it's an actual issue 
 with the project rather than your usage mistake, feel free to post a quick question briefly 
 (actual amount of details depends on the situation) describing the situation and expect to 
 either get a suitable answer or a request to provide a detailed problem report on GitHub 
 which will be treated with more attention. In case of an absence of a GitHub account and 
 unwillingness to create one, detailed report can also be submitted via Matrix and an issue 
 will be opened on GitHub by a maintainer.

### When Starting a Discussion on Matrix

- Clearly state your topic or question.
- Provide context, including your environment (OS, hardware, etc.) if relevant.
- Be patient and respectful while waiting for responses. Feel free to "ping" (draw attention) after some time if it looks like your question wasn't noticed.
- Structure your topic effectively with a clear title and organized content.
- Use code blocks for command outputs or error messages.
- Consider breaking complex topics into smaller, manageable questions.
- Tag your topic with relevant keywords.

### When Opening an Issue on GitHub
- Search globally on linuxboot organization for related keywords first.
  - EG: yubikey search in issues: https://github.com/search?q=org%3Alinuxboot+yubikey&type=issues
- Choose a clear and descriptive title.
- Clearly describe the problem or suggestion:
  - Summarize the issue or feature request.
  - Explain current behavior and expected behavior.
  - For bugs, provide steps to reproduce.
  - For feature requests, explain use case and benefits.
- Mention your environment details.
- If you have a proposed solution, describe it briefly.
- Check for related issues or pull requests and link them.
- Format your issue for readability using Markdown. 
  - Here is a nice advanced online editor alternative to GitHub: https://stackedit.io/app#
- Be responsive to follow-up questions.

### For Pull Requests

- Link to related issues or discussions.
- Provide a clear description of the changes and their purpose.
- Be responsive to feedback and prepared to make adjustments.
- **Important**: All commits to linuxboot/heads (*not heads-wiki!*) must be signed. 
  - For instructions, see: [Signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)
  - If you won't GPG-sign your commits (GitHub signature doesn't count), they will get signed by a maintainer after a successful review, but it's strongly preferred you do it yourself.

## GitHub Repositories

- **linuxboot/heads**: https://github.com/linuxboot/heads
  - Main repository for code, development, and user experience improvements.
  - All commits must be signed.
- **linuxboot/heads-wiki**: https://github.com/linuxboot/heads-wiki
  - Repository for project documentation.
  - Content is rendered and searchable at https://osresearch.net
  - *Commits don't have to be signed to lower bar for contribution*.

We appreciate your contributions to the LinuxBoot/Heads project!