From e2e4d3deacb322849ed3f677720ee9dc5896d94f Mon Sep 17 00:00:00 2001 From: Thierry Laurion Date: Fri, 12 Jul 2024 09:52:31 -0400 Subject: [PATCH] CONTRIBUTING.md: add baselines and refer in README.md Signed-off-by: Thierry Laurion --- CONTRIBUTING.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 26 +++++++++++--------- 2 files changed, 79 insertions(+), 11 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..06f6972f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,64 @@ +# Contributing to LinuxBoot/Heads + +Thank you for your interest in contributing to LinuxBoot/Heads! We welcome contributions +from everyone. By participating in this project, respecting these contribution guidelines +will ease and fasten their review, fixing and merging. + +## 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. +- 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) + +## 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! diff --git a/README.md b/README.md index d3f1a5b6..cda6d788 100644 --- a/README.md +++ b/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`