Guidelines for contributing under CONTRIBUTING.md

CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# 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!

README.md

@@ -1,7 +1,7 @@
 ![Heads booting on an x230](https://user-images.githubusercontent.com/827570/156627927-7239a936-e7b1-4ffb-9329-1c422dc70266.jpeg)
 
 Heads: the other side of TAILS
-===
+==
 
 Heads is a configuration for laptops and servers that tries to bring
 more security to commodity hardware.  Among its goals are:
@@ -25,28 +25,32 @@ Documentation
 ===
 Please refer to [Heads-wiki](https://osresearch.net) for your Heads' documentation needs.
 
+Contributing
+===
+We welcome contributions to the Heads project! Before contributing, please read our [Contributing Guidelines](CONTRIBUTING.md) for information on how to get started, submit issues, and propose changes.
+
 
 Building heads
-===
+==
 
 Under QubesOS?
-====
+===
 * Setup nix persistent layer under QubesOS (Thanks @rapenne-s !)
   * https://dataswamp.org/~solene/2023-05-15-qubes-os-install-nix.html
 * Install docker under QubesOS (imperfect old article of mine. Better somewhere?)
   * https://gist.github.com/tlaurion/9113983bbdead492735c8438cd14d6cd
 
 Build docker from nix develop layer locally
-====
+===
 
 #### Set up Nix and flakes  
 
-* If you don't already have Nix, install it:  
-    * `[ -d /nix ] || sh <(curl -L https://nixos.org/nix/install) --no-daemon`  
-    * `. /home/user/.nix-profile/etc/profile.d/nix.sh`  
-* Enable flake support in nix  
-    * `mkdir -p ~/.config/nix`  
-    * `echo 'experimental-features = nix-command flakes' >>~/.config/nix/nix.conf`  
+* If you don't already have Nix, install it:
+    * `[ -d /nix ] || sh <(curl -L https://nixos.org/nix/install) --no-daemon`
+    * `. /home/user/.nix-profile/etc/profile.d/nix.sh`
+* Enable flake support in nix
+    * `mkdir -p ~/.config/nix`
+    * `echo 'experimental-features = nix-command flakes' >>~/.config/nix/nix.conf`
 
 
 #### Build image
@@ -74,7 +78,7 @@ Done!
 Your local docker image "linuxboot/heads:dev-env" is ready to use, reproducible for the specific Heads commit used and will produce ROMs reproducible for that Heads commit ID.
 
 Jump into nix develop created docker image for interactive workflow
-=====
+====
 `docker run -e DISPLAY=$DISPLAY --network host --rm -ti -v $(pwd):$(pwd) -w $(pwd) linuxboot/heads:dev-env`