From b65aa32fbb02571d4f72563da2a538042f8b27f2 Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Thu, 20 Nov 2025 10:18:20 +0100 Subject: [PATCH] .github: markdown syntax fixes and new section on code signing Signed-off-by: Joachim Wiberg --- .github/CHECKLIST.md | 56 +++++------ .github/CONTRIBUTING.md | 218 ++++++++++++++++++++++++++++------------ 2 files changed, 181 insertions(+), 93 deletions(-) diff --git a/.github/CHECKLIST.md b/.github/CHECKLIST.md index f6e6ed92..102bd411 100644 --- a/.github/CHECKLIST.md +++ b/.github/CHECKLIST.md @@ -3,41 +3,39 @@ Checklists for Pull Requests and Releases Maintainer checklists for reviewing pull requests and doing releases. - Pull Requests ------------- - - If applicable, is there a readable ChangeLog entry? - - If any LICENSE file has been updated, has the `.hash` file been updated? - - If any change to a Finit `.svc` file, does any run/task linger? - I.e., is there a runlevel and/or condition defined to prevent them - from running outside of their intended runlevel? - - If any change to grub or qemu/qeneth setup, has it been tested in GNS3? - - If any change to u-boot/buildroot, has it been tested with `_defconfig` - - If any change to logging, have the resulting logs been audited? - - Check for duplicate entries, misspellings - - Check for sneaky severity changes, e.g., error vs note, error vs warning - - If new subsystem, or major changes to a subsystem, have the docs been updated? - - If change to mDNS, has it been tested with netbrowse? - - If change to `_defconfig`, verify `local.mk` and sync with other archs - - Test manually as well, e.g., CLI changes do not have ha regression tests - - Build from distclean, or use artifacts built by build servers, for manual tests - +- If applicable, is there a readable ChangeLog entry? +- If any LICENSE file has been updated, has the `.hash` file been updated? +- If any change to a Finit `.svc` file, does any run/task linger? + I.e., is there a runlevel and/or condition defined to prevent them + from running outside of their intended runlevel? +- If any change to grub or qemu/qeneth setup, has it been tested in GNS3? + - If any change to u-boot/buildroot, has it been tested with `_defconfig` +- If any change to logging, have the resulting logs been audited? + - Check for duplicate entries, misspellings + - Check for sneaky severity changes, e.g., error vs note, error vs warning +- If new subsystem, or major changes to a subsystem, have the docs been updated? +- If change to mDNS, has it been tested with netbrowse? +- If change to `_defconfig`, verify `local.mk` and sync with other archs + - Test manually as well, e.g., CLI changes do not have ha regression tests + - Build from distclean, or use artifacts built by build servers, for manual tests Releases -------- Recommended checkpoints, use at your own discretion: - - Make at least one -betaN release to verify the GitHub workflow well in time release day - - Stuff happens, remember kernelkit/infix#735 - - Make at least one -rcN to flush out any issues in customer repos - - Easy to forget adaptations/hacks in customer repos -- may need Infix change/support - - Verify release artifacts (checksums, completeness, no corrupted files) - - Test on actual hardware for at least one architecture - - Review ChangeLog for completeness - - Check for release-blocking issues - - Verify generated GNS3 appliance, no marketplace update on -rc builds - - Ensure the markdown link for the release diff is updated - - Ensure subrepos are tagged (can be automated, see kernelkit/infix#393) - - Sync tags for all repo. sync activities +- Make at least one -betaN release to verify the GitHub workflow well in time release day + - Stuff happens, remember kernelkit/infix#735 +- Make at least one -rcN to flush out any issues in customer repos + - Easy to forget adaptations/hacks in customer repos -- may need Infix change/support +- Verify release artifacts (checksums, completeness, no corrupted files) +- Test on actual hardware for at least one architecture +- Review ChangeLog for completeness +- Check for release-blocking issues +- Verify generated GNS3 appliance, no marketplace update on -rc builds +- Ensure the markdown link for the release diff is updated +- Ensure subrepos are tagged (can be automated, see kernelkit/infix#393) +- Sync tags for all repo. sync activities diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 2d59be9b..9da11b2b 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -9,15 +9,15 @@ forms of collaboration as well. [Let's talk!][support] :handshake: If you are unsure how to start implementing an idea or fix: - - :bug: open an issue, there are human friendly templates for _bugs_ - and _feature requests_ at - - :speech_balloon: use the [Q&A Forum][discuss] - - :technologist: The [Developer's Guide][devguide] is also a useful start +- :bug: open an issue, there are human friendly templates for _bugs_ + and _feature requests_ at +- :speech_balloon: use the [Q&A Forum][discuss] +- :technologist: The [Developer's Guide][devguide] is also a useful start -> _Talking about code and problems first is often the best way to get +> [!IMPORTANT] +> Talking about code and problems first is often the best way to get > started before submitting a pull request. We have found it always -> saves time, yours and ours._ - +> saves time, yours and ours. :sparkles: General Guidelines ----------------------------- @@ -27,21 +27,20 @@ version the change is made against, what it does, and, more importantly *why* -- from your perspective, why is it a bug, why does the code need changing in this way. Start with why. - - :bug: Bug reports need metadata like Infix version or commit hash - - :adhesive_bandage: Bug fixes also need version, and (preferably) a - corresponding issue number for the ChangeLog - - :new: New features, you need to get approval of the YANG model first! - :speech_balloon: Please use the [Forum][discuss], e.g., category: - *Ideas*, or open a :pray: feature request issue - - :white_check_mark: New features also need new regression tests, this - can be basic tests or more complex use-case tests comprising multiple - subsystems, see [Testing Changes](#test_tube-testing-changes), below +- :bug: Bug reports need metadata like Infix version or commit hash +- :adhesive_bandage: Bug fixes also need version, and (preferably) a + corresponding issue number for the ChangeLog +- :new: New features, you need to get approval of the YANG model first! + :speech_balloon: Please use the [Forum][discuss], e.g., category: + *Ideas*, or open a :pray: feature request issue +- :white_check_mark: New features also need new regression tests, this + can be basic tests or more complex use-case tests comprising multiple + subsystems, see [Testing Changes](#test_tube-testing-changes), below Please take care to ensure you follow the project coding style and the commit message format. If you follow these recommendations you help the maintainers and make it easier for them to include your code. - :woman_technologist: Coding Style --------------------------------- @@ -51,39 +50,40 @@ and it is expected that you provide a human-readable summary for the release notes (ChangeLog) and at least a configuration example in the manual for new features. -> **Tip:** consider ["Readme driven development"][RDD] for new features. -> It is amazing how many flaws in your own bright ideas come to bare -> when you suddenly have to explain them to someone else! +> [!TIP] +> Consider ["Readme driven development"][RDD] for new features. It is +> amazing how many flaws in your own bright ideas come to bare when you +> suddenly have to explain them to someone else! We expect code contributions for: - - C code in [Linux Coding Style][Linux] - - Python code should follow [PEP-8][] +- C code in [Linux Coding Style][Linux] +- Python code should follow [PEP-8][] +> [!IMPORTANT] > **However,** always submit code that follows the style of surrounding > code! Legacy takes precedence, and remember, we read code a lot more > than write it, so legibility is important. The ChangeLog deserves a separate mention: - - Releases are listed in reverse chronological order order, so the - latest/next release is at the beginning of the file - - Only *user-facing bugs and features* are detailed, so code refactor, - new tests, etc. are not listed. - - Add your changes/features to the Changes section - - Add your Fix line in the Fixes section, in numeric order - - Changes and fixes without an issue number are listed after all - numbered ones - - YANG model changes are documented in their respective model, for - standard models, e.g., for `ietf-interfaces.yang`, the corresponding - `infix-interfaces.yang` detail augments/deviations as revisions. +- Releases are listed in reverse chronological order order, so the + latest/next release is at the beginning of the file +- Only *user-facing bugs and features* are detailed, so code refactor, + new tests, etc. are not listed. +- Add your changes/features to the Changes section +- Add your Fix line in the Fixes section, in numeric order +- Changes and fixes without an issue number are listed after all + numbered ones +- YANG model changes are documented in their respective model, for + standard models, e.g., for `ietf-interfaces.yang`, the corresponding + `infix-interfaces.yang` detail augments/deviations as revisions. A final note, lines of code are allowed to be longer than 72 characters these days, unless you live by PEP-8 (see above). There is no enforced maximum, but the team usually keep it around 100 characters for both C and Python. - :test_tube: Testing Changes --------------------------- @@ -97,9 +97,8 @@ the same pull request. For help getting started with testing, see the following resources: - - [Developer's Guide][devguide] - - [Regression Testing][testing] - +- [Developer's Guide][devguide] +- [Regression Testing][testing] :memo: Commit Messages ---------------------- @@ -110,45 +109,135 @@ proud of your work and set up a proper GIT identity for your commits: - $ git config --global user.name "Jacky Linker" - $ git config --global user.email jacky.linker@example.com +```bash +$ git config --global user.name "Jacky Linker" +$ git config --global user.email jacky.linker@example.com +``` Example commit message from one of many [online guides][cbeams]. Use `git commit -s` to automatically add a `Signed-off-by` for proof of origin, see [DCO][] for more info. - subsystem: brief, but clear and concise summary of changes - - More detailed explanatory text, if necessary. Wrap it to about 72 - characters or so. In some contexts, the first line is treated as - the subject of an email and the rest of the text as the body. The - empty line separating summary from body is critical. Tools like - rebase can get confused if the empty line is missing. - - Further paragraphs should be separated with empty lines. - - - Bullet points are okay, too - - - Typically a hyphen or asterisk is used for the bullet, preceded - by a single space, with blank lines in between, but conventions - vary here +```text +subsystem: brief, but clear and concise summary of changes - If you use an issue tracker, put references to them at the bottom, - like this: +More detailed explanatory text, if necessary. Wrap it to about 72 +characters or so. In some contexts, the first line is treated as +the subject of an email and the rest of the text as the body. The +empty line separating summary from body is critical. Tools like +rebase can get confused if the empty line is missing. - Resolves: #123 - See also: #456, #789 +Further paragraphs should be separated with empty lines. - Signed-off-by: Jacky Linker + - Bullet points are okay, too + + - Typically a hyphen or asterisk is used for the bullet, preceded + by a single space, with blank lines in between, but conventions + vary here + +If you use an issue tracker, put references to them at the bottom, +like this: + +Resolves: #123 +See also: #456, #789 + +Signed-off-by: Jacky Linker +``` This is an example of how to [automatically close][closing] an issue when the commit is merged to mainline. Several keywords are available. +:lock_with_ink_pen: Signing Commits with GPG +--------------------------------------------- + +To ensure the authenticity and integrity of your contributions, we +**require** all commits to be signed with GPG. This cryptographically +verifies that commits come from a trusted source. + +### Generating a GPG Key + +If you don't already have a GPG key, generate one: + +```bash +$ gpg --full-generate-key +``` + +When prompted, choose: +- Key type: `RSA and RSA` (default) +- Key size: `4096` bits (recommended for security) +- Expiration: `0` (key does not expire) +- Real name and email: Use the same email as your Git configuration + +> [!NOTE] +> We recommend keys that do not expire for signing commits. Expiration +> creates a "usability time bomb" without providing meaningful security +> benefits for code signing. See [this article][pgpfan] for details. + +### Configuring Git to Sign Commits + +First, find your GPG key ID: + +```bash +$ gpg --list-secret-keys --keyid-format=long +``` + +Look for the line starting with `sec`, the key ID is the part after the `/`. +For example, in `sec rsa4096/ABCD1234EFGH5678`, the key ID is `ABCD1234EFGH5678`. + +Configure Git to use your GPG key: + +```bash +$ git config --global user.signingkey ABCD1234EFGH5678 +$ git config --global commit.gpgsign true +``` + +The second command enables automatic signing for all commits. Alternatively, +you can sign individual commits with `git commit -S`. + +### Publishing Your Public Key + +To allow others to verify your signatures, publish your public key to a +keyserver: + +```bash +$ gpg --keyserver hkps://keys.openpgp.org --send-keys ABCD1234EFGH5678 +``` + +> [!IMPORTANT] +> The keyserver will send a verification email to the address associated +> with your key. You **must** click the link in that email to confirm +> ownership before your key becomes searchable by email address. + +Alternative keyservers you can use: +- `hkps://keyserver.ubuntu.com` +- `hkps://pgp.mit.edu` + +### Adding Your GPG Key to GitHub + +For GitHub to show your commits as "Verified", you need to add your public +key to your account: + +1. Export your public key: + ```bash + $ gpg --armor --export ABCD1234EFGH5678 + ``` + +2. Copy the entire output, including the `-----BEGIN PGP PUBLIC KEY BLOCK-----` + and `-----END PGP PUBLIC KEY BLOCK-----` lines. + +3. Go to [GitHub Settings → SSH and GPG keys](https://github.com/settings/keys) + +4. Click **New GPG key** and paste your public key. + +Now your signed commits will display a "Verified" badge on GitHub! :white_check_mark: + +For more details, see GitHub's [official documentation on commit signature verification][gpg-verify]. :twisted_rightwards_arrows: Pull Requests ----------------------------------------- -> _The git repository is the canonical location for information._ +> [!NOTE] +> _The git repository is the canonical location for all information._ A pull request should preferably address a single issue or change. This may of course include multiple related changes, but what is important to @@ -167,7 +256,6 @@ Buildroot, consider the pull request message body similar to the cover letter for a series of patches -- it's a summary of changes, and it is lost when the changes are merged to the mainline branch. - :balance_scale: Code of Conduct ------------------------------- @@ -184,6 +272,8 @@ other contributions that are not aligned to this Code of Conduct."* [PEP-8]: https://peps.python.org/pep-0008/ [RDD]: https://tom.preston-werner.com/2010/08/23/readme-driven-development [cbeams]: https://cbea.ms/git-commit/#seven-rules -[conduct]: CODE-OF-CONDUCT.md -[DCO]: https://developercertificate.org/ -[closing]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests +[conduct]: CODE-OF-CONDUCT.md +[DCO]: https://developercertificate.org/ +[closing]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests +[gpg-verify]: https://docs.github.com/en/authentication/managing-commit-signature-verification +[pgpfan]: https://articles.59.ca/doku.php?id=pgpfan:expire