# 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.

### 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!