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

[Kamil Konieczny]

Hi Hajda,,
On 2025-03-31 at 12:56:10 +0200, Hajda, Andrzej wrote:
> 
> 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.
> > 

+cc
Cc: Andrzej Hajda <andrzej.hajda at intel.com>
Cc: Zbigniew Kempczyński <zbigniew.kempczynski at intel.com>

> > 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?
> 

I wasn't sure which word to use, maybe I should just drop it:

then consider to write also __function() without them;

What I mean was a function with same functionality but without any
macros affecting test control flow, so no igt_assert nor igt_require
nor other.

> 
> > +  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
> 

Well, printing really should be done in tests, libs could guess what
should/could be printed but best place for them is test itself.
Unless someone wrote lib function just for printing. Hmm, maybe I will
drop these two lines.

Regards,
Kamil

> 
> > +
> > +- 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
> >   ---------------