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 <emil.l.velikov@gmail.com>
Link: https://github.com/kmod-project/kmod/pull/122
Signed-off-by: Lucas De Marchi <lucas.de.marchi@gmail.com>

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644 (file)
index 0000000..c672c11
--- /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 02208bfe4093299a7c65ba1f1948b6d0f894336e..e23cc0376ffbb115bd85a9291996ff3eb357468a 100644 (file)
--- 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
 ====================================