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

[Ser, Simon]

On Thu, 2019-06-27 at 15:57 +0300, Arkadiusz Hiler wrote:
> On Thu, Jun 20, 2019 at 04:49:39PM +0300, Ser, Simon wrote:
> > On Mon, 2019-06-17 at 13:54 +0300, Arkadiusz Hiler wrote:
> > > 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()
> > > 
> > > Cc: Petri Latvala <petri.latvala at intel.com>
> > > Reviewed-by: Arkadiusz Hiler <arkadiusz.hiler at intel.com>
> > 
> > Should that be a S-o-b instead?
> 
> oops
> 
> > > ---
> > >  CONTRIBUTING.md | 46 ++++++++++++++++++++++++++++++++++++----------
> > >  1 file changed, 36 insertions(+), 10 deletions(-)
> > > 
> > > diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
> > > index d3a3d099..7deba078 100644
> > > --- a/CONTRIBUTING.md
> > > +++ b/CONTRIBUTING.md
> > > @@ -1,9 +1,41 @@
> > > +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.
> > 
> > Do we have a link to this generated documentation somewhere?
> > 
> > > +- 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 for more
> > > +  details.
> > 
> > Again, a direct link would be nice.
> 
> I'll put it near the top of README. Is that enough or do you still see
> some value in having it also linked here?

I still think a direct link to igt_describe would save the reader from
searching it in the docs. Since these docs contain nice examples,
making it frictionless to access them while preparing a first IGT
contribution would be cool.