[PATCH] docs/drm: Add a new bullet to the uAPI requirements

[Daniel Vetter]

On Wed, Aug 4, 2021 at 8:50 PM Jason Ekstrand <jason at jlekstrand.net> wrote:
>
> On Wed, Aug 4, 2021 at 1:48 PM Jason Ekstrand <jason at jlekstrand.net> wrote:
> >
> > While tracking down various bits of i915 uAPI, it's been difficult to
> > find the userspace much of the time because no one bothers to mention it
> > in commit messages.  Require the kernel patch to be a one-stop shop for
> > finding the various bits which were used to justify the new uAPI.
> >
> > Signed-off-by: Jason Ekstrand <jason at jlekstrand.net>
> > Cc: Daniel Vetter <daniel.vetter at ffwll.ch>
> > Cc: Dave Airlie <airlied at redhat.com>
> > ---
> >  Documentation/gpu/drm-uapi.rst | 5 +++++
> >  1 file changed, 5 insertions(+)
> >
> > diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
> > index 199afb503ab1..82f780bc3fce 100644
> > --- a/Documentation/gpu/drm-uapi.rst
> > +++ b/Documentation/gpu/drm-uapi.rst
> > @@ -109,6 +109,11 @@ leads to a few additional requirements:
> >    userspace patches land. uAPI always flows from the kernel, doing things the
> >    other way round risks divergence of the uAPI definitions and header files.
> >
> > +- The kernel patch which adds the new uAPI **must** reference the patch series
> > +  or merge requests in the userspaces project which use the new uAPI and
>
> Locally, I've done s/project which use/projects which demonstrate/

While we paint this shed ... projects which demonstrate the use of the new uAPI?

Either way this seems like a fine addition to our docs and process,
since grepping through all the things just to figure out what
something does because documentation was deemed optional too gets
boring.

Acked-by: Daniel Vetter <daniel.vetter at ffwll.ch>

-Daniel

>
> --Jason
>
> > +  against which the review was done so that future developers can find all of
> > +  the pieces which tie together.
> > +
> >  These are fairly steep requirements, but have grown out from years of shared
> >  pain and experience with uAPI added hastily, and almost always regretted about
> >  just as fast. GFX devices change really fast, requiring a paradigm shift and
> > --
> > 2.31.1
> >



-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch