[igt-dev] [PATCH i-g-t 4/5] CONTRIBUTING: Rework a bit and update

Arkadiusz Hiler
2019-07-01T12:22:10Z

I have split the main body of the CONTRIBUTING file to 3 sections:
* the short welcome message
* the code - styling, suggestions
* sending patches - licensing informations, mailing lists, reviews, etc.

Changes for the code section contents:
* link to the kernel coding style docs
* be more clear on subtest naming
* mention igt_describe()

v2: Add link to the online documentation for igt-describe. It will start
working once the series is merged. (Simon)

Cc: Petri Latvala <petri.latvala@intel.com>
Cc: Simon Ser <simon.ser@intel.com>
Signed-off-by: Arkadiusz Hiler <arkadiusz.hiler@intel.com>
Acked-by: Petri Latvala <petri.latvala@intel.com>
---
CONTRIBUTING.md | 48 ++++++++++++++++++++++++++++++++++++++----------
1 file changed, 38 insertions(+), 10 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d3a3d099..6d1294ad 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,9 +1,43 @@
+CONTRIBUTING
+============
+
Patches to igt-gpu-tools are very much welcome, we really want this to be the
universal set of low-level tools and testcases for kernel graphics drivers
on Linux and similar platforms. So please bring on porting patches, bugfixes,
improvements for documentation and new tools and testcases.

-A short list of contribution guidelines:
+
+The Code
+--------
+
+- The code should follow kernel coding style:
+ https://www.kernel.org/doc/html/latest/process/coding-style.html
+
+- Testcases (subtests) have to use minus signs (-) as a word separator.
+ The generated documentation contains glossary of commonly used terms.
+
+- All new test have to be described using `igt_describe()` family of
+ functions. The description should contain the spirit of the test (what is
+ the general idea behind the test) and *not* the letter (C to English
+ translation of the test). Refer to [`igt_describe()`
+ documentation][igt-describe] for more details.
+
+- The generated documentation contains explanation of magic control blocks like
+ `igt_subtest` and `igt_fixture`. Please make sure that you understand their
+ roles and limitation before using/altering them.
+
+- Also please make full use of all the helpers and convenience macros
+ provided by the igt library. The semantic patch lib/igt.cocci can help with
+ more automatic conversions.
+
+[igt-describe]: https://drm.pages.freedesktop.org/igt-gpu-tools/igt-gpu-tools-Core.html#igt-describe
+
+
+Sending Patches
+---------------
+
+- igt-gpu-tools is MIT licensed and we require contributions to follow the
+ developer's certificate of origin: http://developercertificate.org/

- Please submit patches formatted with git send-email/git format-patch or
equivalent to:
@@ -23,14 +57,6 @@ A short list of contribution guidelines:

on its first invocation.

-- igt-gpu-tools is MIT licensed and we require contributions to follow the
- developer's certificate of origin: http://developercertificate.org/
-
-- When submitting new testcases please follow the naming conventions documented
- in the generated documentation. Also please make full use of all the helpers
- and convenience macros provided by the igt library. The semantic patch
- lib/igt.cocci can help with the more automatic conversions.
-
- Patches need to be reviewed on the mailing list. Exceptions only apply for
testcases and tooling for drivers with just a single contributor (e.g. vc4).
In this case patches must still be submitted to the mailing list first.
@@ -46,7 +72,8 @@ A short list of contribution guidelines:
- Changes to the testcases are automatically tested. Take the results into
account before merging.

-Commit rights
+
+Commit Rights
-------------

Commit rights will be granted to anyone who requests them and fulfills the
@@ -80,6 +107,7 @@ come back to the project.
Maintainers and committers should encourage contributors to request commit
rights, especially junior contributors tend to underestimate their skills.

+
Code of Conduct
---------------

--
2.21.0