[PATCH i-g-t v1 2/2] CONTRIBUTING: Add guide about igt libraries

[Hajda, Andrzej]

W dniu 27.03.2025 o 16:31, Kamil Konieczny pisze:
> Add some general guide about adding new library function and
> a few guides for their usage outside of tests.
>
> Signed-off-by: Kamil Konieczny <kamil.konieczny at linux.intel.com>
> ---
>   CONTRIBUTING.md | 27 +++++++++++++++++++++++++++
>   1 file changed, 27 insertions(+)
>
> diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
> index b571b5e68..d85266a6c 100644
> --- a/CONTRIBUTING.md
> +++ b/CONTRIBUTING.md
> @@ -38,6 +38,33 @@ The Code
>   
>   [igt-describe]: https://drm.pages.freedesktop.org/igt-gpu-tools/igt-gpu-tools-Core.html#igt-describe
>   
> +IGT libraries
> +-------------
> +- Tests and benchmarks are the main usage of IGT libraries, so they
> +  could use test specific macros/functions, for example igt_assert,
> +  igt_require, igt_skip, igt_info or igt_debug.
> +
> +- New library function could be written when it will have at least two
> +  different users, for example if it could be used by two or more tests.
> +
> +- In a new library function():
> +  if it has macros (for example igt_assert/igt_require/igt_skip) then
> +    write also __function() counterpart without them;


Not sure what does it mean. What are counterparts to above macros?


> +  limit also usage of prints igt_info/igt_debug, this should be a part
> +    of test code.


As Zbyszek mentioned, beside pure lib functions which should be rather 
quiet, there is bunch of code shared between different tests, I am not 
sure if this should apply to this code.

On the other side I am not sure how to emphasise difference between 
them, comment?


Regards

Andrzej


> +
> +- Libraries and igt_runner
> +  Runner should not use lib functions. It is crucial for CI runs so using
> +  libraries puts a risk of bringing changes meant for tests which in turn
> +  could break runner.
> +  Note: You will find places where igt_runner uses lib functions - this will
> +  be on ToDo list to be fixed.
> +
> +- Libraries and tools/
> +  Tools should try to not use lib functions. Any abnormal condition should
> +  be simply reported by printf or fprintf to stdout/stderr and then tool
> +  should exit gracefully. Do not use igt_abort nor igt_assert, igt_print,
> +  igt_debug nor other testing/printing macros from igt lib/
>   
>   Sending Patches
>   ---------------