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.

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