Re: [PATCH 2/2] drm/doc: Add RFC section

From: Daniel Vetter <daniel@ffwll.ch>
To: Rodrigo Vivi <rodrigo.vivi@intel.com>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>,
	Intel Graphics Development <intel-gfx@lists.freedesktop.org>,
	DRI Development <dri-devel@lists.freedesktop.org>,
	Jason Ekstrand <jason@jlekstrand.net>,
	Daniel Vetter <daniel.vetter@intel.com>,
	Dave Airlie <airlied@redhat.com>
Subject: Re: [PATCH 2/2] drm/doc: Add RFC section
Date: Tue, 23 Mar 2021 14:10:17 +0100	[thread overview]
Message-ID: <YFnouVsaKs2odAqq@phenom.ffwll.local> (raw)
In-Reply-To: <YFng89ujYxcyJQmN@intel.com>

On Tue, Mar 23, 2021 at 08:37:07AM -0400, Rodrigo Vivi wrote:
> On Tue, Mar 23, 2021 at 09:44:53AM +0100, Daniel Vetter wrote:
> > Motivated by the pre-review process for i915 gem/gt features, but
> > probably useful in general for complex stuff.
> > 
> > Cc: Jani Nikula <jani.nikula@linux.intel.com>
> > Cc: Joonas Lahtinen <joonas.lahtinen@linux.intel.com>
> > Cc: Rodrigo Vivi <rodrigo.vivi@intel.com>
> > Cc: Jason Ekstrand <jason@jlekstrand.net>
> > Cc: Dave Airlie <airlied@redhat.com>
> > Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> > ---
> >  Documentation/gpu/index.rst |  1 +
> >  Documentation/gpu/rfc.rst   | 16 ++++++++++++++++
> >  2 files changed, 17 insertions(+)
> >  create mode 100644 Documentation/gpu/rfc.rst
> > 
> > diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
> > index c9a51e3bfb5a..df58cb826d68 100644
> > --- a/Documentation/gpu/index.rst
> > +++ b/Documentation/gpu/index.rst
> > @@ -16,6 +16,7 @@ Linux GPU Driver Developer's Guide
> >     vga-switcheroo
> >     vgaarbiter
> >     todo
> > +   rfc
> 
> I understand the motivation here so I didn't commented earlier, but looking now,
> I'm wondering that this section will polute the official doc...

We already have this problem between documentation meant for kernel driver
developers and documentation meant for userspace developers around uapi
and all that. "who is the audience here" is very ill-defined for our
current set of docs in Documentation/gpu :-(

So I agree with you, but I also don't think this will make things worse.
-Daniel

> 
> >  
> >  .. only::  subproject and html
> >  
> > diff --git a/Documentation/gpu/rfc.rst b/Documentation/gpu/rfc.rst
> > new file mode 100644
> > index 000000000000..9d0ff2921af8
> > --- /dev/null
> > +++ b/Documentation/gpu/rfc.rst
> > @@ -0,0 +1,16 @@
> > +===============
> > +GPU RFC Section
> > +===============
> > +
> > +For complex work, especially new uapi, it is often good to nail the high level
> > +design issues before getting lost in the code details. This section is meant to
> > +host such documentation:
> > +
> > +* Each RFC should be a section in this file, explaining the goal and main design
> > +  considerations.
> > +
> > +* For uapi structures add a file to this directory with and then pull the
> > +  kerneldoc in like with real uapi headers.
> > +
> > +* Once the code has landed move all the documentation to the right places in
> > +  the main core, helper or driver sections.
> > -- 
> > 2.31.0
> > 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel