From: Emil Velikov Date: Mon, 9 Sep 2024 15:14:54 +0000 (+0100) Subject: CONTRIBUTING.md: add initial contributing guideline X-Git-Tag: v34~366 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=ea8e6f3a0c4bd07b52048c58a868ca332640cd03;p=thirdparty%2Fkmod.git CONTRIBUTING.md: add initial contributing guideline Document some of the practises and expectations that we've been using in the project. Large chunks of the document are inspired by wlroots - thank you o/ Going further, I think we'd want to document the use of SoB/DCO and mention about our CI pipelines, so that people try them before opening PRs/sending patches. Although I think that can follow-up at another day. Signed-off-by: Emil Velikov Link: https://github.com/kmod-project/kmod/pull/122 Signed-off-by: Lucas De Marchi --- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..c672c116 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,77 @@ +# Contributing to kmod + +Thanks for taking the time to contribute to kmod! + +If you want to submit changes, you can submit GitHub [pull requests] as well as +patches sent to the [mailing list]. In addition you can open issues and feature +requests on our [GitHub tracker]. + +## Commits + +The kmod project uses a [linear, "recipe" style] history. This means that +commits should be small, digestible, stand-alone, and functional. + +Commit messages are in imperative mood and merges are to be avoided. + +When in doubt, or need a regresher, checking through the output of `git log` is +highly recommended. + +## Commit tags + +Commit messages, apart from stating why a particular change is made, can include +a range of tags. + +### Issues, feature requests + +Whenever a patch resolves a particular issue, be that one on our [GitHub +tracker] or elsewhere, use the `Closes:` tag followed by the full URL. + + Closes: https://github.com/kmod-project/kmod/issues/65 + +### Discussions, references + +If your commit covers a topic raised in an issue, but no the issue itself, or +otherwise refers to a more complicated topic, you can use `Reference:` + +### Bugfixes, regressions + +Nobody is perfect and regressions happen from time to time. Whenever a commit +addresses a regression caused by another commit, use `Fixes:` as below: + + Fixes: 38943b2 ("shared: use size_t for strbuf") + +## Coding style + +The project uses style practically identical to the kernel style. You can see +the in-tree [CODING-STYLE file](CODING-STYLE) for quick references. + +We also have a [.clang-format file](.clang-format) to ease and enforce the +style. Make sure you run git-clang-format against your changes, before +submitting PRs/patches. + +## Documentation + +The official libkmod documentation is generated by [gtk-doc] and a simple test +is wired to `meson test` to catch accidental mistakes or omissions. + +If you're unfamiliar with gtk-doc here is a [quick primer]. + +## Manual pages + +Our manual pages are written in [scdoc] a simple [markdown-like syntax]. Please +make sure to update them as you add new options to the kmod tools. + +## Shell completions + +The project aims to provide bash, zsh and fish shell completions for all the +kmod tools. Currently support is borderline non-existent, so your help is +greatly appreciated. + +[pull requests]: https://github.com/kmod-project/kmod/pull/ +[mailing list]: mailto:linux-modules@vger.kernel.org +[GitHub tracker]: https://github.com/kmod-project/kmod/issues/ +[linear, "recipe" style]: https://www.bitsnbites.eu/git-history-work-log-vs-recipe/ +[gtk-doc]: https://gitlab.gnome.org/GNOME/gtk-doc +[quick primer]:https://gi.readthedocs.io/en/latest/annotations/gtkdoc.html +[scdoc]: https://sr.ht/~sircmpwn/scdoc/ +[markdown-like syntax]: https://man.archlinux.org/man/scdoc.5.en diff --git a/README.md b/README.md index 02208bfe..e23cc037 100644 --- a/README.md +++ b/README.md @@ -72,8 +72,8 @@ When working on kmod, use the included `build-dev.ini` file, as: meson setup --native-file build-dev.ini builddir/ -Make sure to read the CODING-STYLE file and the other READMEs: libkmod/README -and testsuite/README. +Make sure to read [our contributing guide](CONTRIBUTING.md) and the other +READMEs: [libkmod](libkmod/README) and [testsuite](testsuite/README). Compatibility with module-init-tools ====================================