RFC: new device tree binding review process idea

RFC: new device tree binding review process idea

[Grant Likely]

Hi all.  I've been thinking for quite a while now about setting up a
wiki for documenting new device tree bindings.  I've finally got
around to setting something up to give it a try and making a first cut
at a peer-review process for new bindings.  I'd like to get some
feedback on what I've set up so far.  Please take a look and let me
know what you think.  The draft review process page is here:

http://fdt.secretlab.ca/Review_Process

I'm also pasting the page contents below to make it easy to review.

g.

----

Device tree 'bindings' document how individual devices are described
in the device tree.  For any given device, the binding says what
properties and nodes a device driver needs to use the device.

This page documents the process for writing and reviewing new
bindings.  New bindings are written for new devices that cannot be
handled by existing bindings.

== Creating a new draft binding ==
* New draft bindings shall be written in plain-text format using the
Mediawiki markup language, ideally as a new page in this wiki.
** Authors aren't required to use the wiki for editing their binding,
but when the new binding is approved they either need to add it to the
wiki themselves, or ask a reviewer to add it for them.
* Page titles for bindings shall be in the form
"Compatible=<compatible value>" which matches the distinguishing
compatible property value used by the binding.
* Binding documents may include Mediawiki Category: tags to group
binding into Vendor and Bus type categories.
* Post new binding text to the
[mailto:devicetree-discuss-uLR06cmDAlY/bJ5BZ2RsiQ@public.gmane.org
devicetree-discuss-uLR06cmDAlY/bJ5BZ2RsiQ@public.gmane.org] mailing list and ask for review.
** Include a link to the wiki page if possible.
* Respond to comments and post updated drafts.

New bindings will be flagged as "unreviewed" on the wiki.

== Modifying an existing binding ==
* Same as for creating new bindings except the diff between the old
and new versions

By default, modifications to approved bindings will not be displayed
until the changes are approved.  The last 'stable' version will be
displayed instead.  The 'draft' tab at the top of the page can be used
to show the modified version.

== Reviewing a binding ==
* Review comments on new and modified bindings can be posted by anyone
on the devicetree-discuss mailing list.
* Authors and reviews should work toward a consensus on the binding.
* When consensus is reached, ask one of the device tree binding
maintainers mark the binding as 'approved'.
* '''(TBD: who are the maintainers going to be?  How does someone
contact the maintainers)'''

== Approval ==
* Binding maintainers have permission to mark bindings as approved in this wiki.

== Notes ==
=== Persistence of bindings ===
* In general, once a binding is approved it cannot be either removed
or changed in an incompatible way.  It can only be deprecated.
** Reason is that changing a binding once device drivers are actually
using it could result in newer OS versions not working with older
device trees.

=== Notes for driver and operating system authors ===
* Bindings shall be documented, reviewed and approved '''before''' any
'official' release of device drivers that use the binding.
** The definition of 'official release' is subject to interpretation
of course, but the principle is that bindings need to be peer-reviewed
to catch problems before committing to use them in an official
release.  Once a binding is used 'in the wild' it becomes difficult to
change.
** For example, in the Linux case code using new bindings will not be
merged into Linus' tree before the binding is reviewed.


-- 
Grant Likely, B.Sc., P.Eng.
Secret Lab Technologies Ltd.

RE: new device tree binding review process idea

[Yoder Stuart-B08248]

> Device tree 'bindings' document how individual devices are described
> in the device tree.  For any given device, the binding says what
> properties and nodes a device driver needs to use the device.
> 
> This page documents the process for writing and reviewing new
> bindings.  New bindings are written for new devices that cannot be
> handled by existing bindings.
> 
> == Creating a new draft binding ==
> * New draft bindings shall be written in plain-text format using the
> Mediawiki markup language, ideally as a new page in this wiki.

I think the review and approval process looks good, no issues
with it.

I do question whether we want bindings created in Mediawiki markup
languages vs just plain text.

I've created a couple of example bindings based on the ePAPR
ns16550 binding (using a binding template we have been using
internally at Freescale for a couple of years):

Plain text: http://fdt.secretlab.ca/Compatible%3Dsry,ns16550-v1

Mediawiki: http://fdt.secretlab.ca/Compatible%3Dsry,ns16550-v2

You could get a lot more fancy than that and use tables or
something, but the more Mediawiki-ized the text gets the harder
it to review the source text on a mailing list.

Another thing to consider is whether eventually we want to 
maintain approved bindings in git.  It would be convenient
to do a git clone of a device-tree-bindings.git repo, be able to
grep it, etc.  Say you want to find all bindings that use
a certain property.   I'm not sure how good the Mediawiki
search is.

So, my vote would be to require a plain text format/template
that should be used with no Mediawiki markup.  The binding
would be posted on the wiki between <pre></pre> tags.

The plain text will give some flexibility in how the binding
could be used in other contexts.

> * Authors and reviews should work toward a consensus on the binding.
> * When consensus is reached, ask one of the device tree binding
> maintainers mark the binding as 'approved'.
> * '''(TBD: who are the maintainers going to be?  How does someone
> contact the maintainers)'''

To start with I think each company should designate a maintainer
for company-specific bindings.

Stuart Yoder

Re: new device tree binding review process idea

[Grant Likely]

Hi Stewart, thanks for the feedback.  Comments below...

On Tue, Apr 6, 2010 at 9:04 AM, Yoder Stuart-B08248
<B08248-KZfg59tc24xl57MIdRCFDg@public.gmane.org> wrote:
>
>> Device tree 'bindings' document how individual devices are described
>> in the device tree.  For any given device, the binding says what
>> properties and nodes a device driver needs to use the device.
>>
>> This page documents the process for writing and reviewing new
>> bindings.  New bindings are written for new devices that cannot be
>> handled by existing bindings.
>>
>> == Creating a new draft binding ==
>> * New draft bindings shall be written in plain-text format using the
>> Mediawiki markup language, ideally as a new page in this wiki.
>
> I think the review and approval process looks good, no issues
> with it.
>
> I do question whether we want bindings created in Mediawiki markup
> languages vs just plain text.
>
> I've created a couple of example bindings based on the ePAPR
> ns16550 binding (using a binding template we have been using
> internally at Freescale for a couple of years):
>
> Plain text: http://fdt.secretlab.ca/Compatible%3Dsry,ns16550-v1
>
> Mediawiki: http://fdt.secretlab.ca/Compatible%3Dsry,ns16550-v2
>
> You could get a lot more fancy than that and use tables or
> something, but the more Mediawiki-ized the text gets the harder
> it to review the source text on a mailing list.

I'm not sure I agree.  I find the mediawiki markup pretty readable.
We can also enforce some rules like "keep text to 80 chars", or "don't
reflow existing text" so that diffs remain sane.

Something I haven't verified yet is whether it is possible to get
MediaWiki to generate unified instead of side-by-side diffs.  If
cannot, then I don't expect it would be too hard to add.  I want to
make it as easy as possible to go from the wiki to an email for
requesting review.

> Another thing to consider is whether eventually we want to
> maintain approved bindings in git.  It would be convenient
> to do a git clone of a device-tree-bindings.git repo, be able to
> grep it, etc.  Say you want to find all bindings that use
> a certain property.   I'm not sure how good the Mediawiki
> search is.

I've got the entire wiki (php & database) backed up into a git repo,
but I can't really publish it because it also contains all user
account information.  I do want to replicate it somehow in case I get
hit by a bus, or hired by Microsoft, or something equally nasty.

MediaWiki does support XML exporting for off-line editing (one of the
reasons I chose mediawiki), so we could have a canned xml export of
approved bindings into a git repo somewhere.  Being able to generate
an off-line copy is something I think is important.

Mediawiki search is pretty good, and google will crawl it, so they can
be used as a secondary search tool.  :-)

> So, my vote would be to require a plain text format/template
> that should be used with no Mediawiki markup.  The binding
> would be posted on the wiki between <pre></pre> tags.
>
> The plain text will give some flexibility in how the binding
> could be used in other contexts.

Personally, I like the idea of using some basic markup, whether it be
mediawiki or something else.  Originally, I considered using gitwiki
which stores everything in a git repo, and uses the markdown markup
format.  I like the idea of anyone being able to clone the repo and
editing it offline.  However, git-wiki is pretty immature, and I don't
want to get into the business of maintaining wiki code.

By using some form of markup, it adds some level of context to the
binding text which can be used to reformat into other forms, while
still remaining readable in plain text (with the possible exception of
tables).  Filters can easily be written to transform from one markup
to another as needed.

Mediawiki is as readable as any, and it's got the advantage of a
stable and well supported application behind it.  I've used mediawiki
for a while now, and it's pretty much proven that it scales well, and
does a good job of handling off-line edits.  Although I would agree
that it makes sense to define a binding template and formating guide
to keep things looking uniform and readable.

>
>> * Authors and reviews should work toward a consensus on the binding.
>> * When consensus is reached, ask one of the device tree binding
>> maintainers mark the binding as 'approved'.
>> * '''(TBD: who are the maintainers going to be?  How does someone
>> contact the maintainers)'''
>
> To start with I think each company should designate a maintainer
> for company-specific bindings.

s/designate/nominate/

Following the Linux lead, I want the caveat that a company doesn't
automatically get to select the maintainer for their parts.  If
someone shows competence and interest in a particular area, then I've
got no problem with him or her being a maintainer regardless of who
that person works for.  The reverse is also true; someone who hasn't
already been involved with binding documentation and review should not
get to be maintainer.

BTW, I haven't forgotten about the comments you made about a year ago
about the wiki regarding licensing.  It's still on my todo list to act
on them.  :-/  Soon, I promise.

-- 
Grant Likely, B.Sc., P.Eng.
Secret Lab Technologies Ltd.

RE: new device tree binding review process idea

[Yoder Stuart-B08248]

> MediaWiki does support XML exporting for off-line editing (one of the
> reasons I chose mediawiki), so we could have a canned xml export of
> approved bindings into a git repo somewhere.  Being able to generate
> an off-line copy is something I think is important.

If there are ways to export the binding text, then that addresses
my concern for the most part.

> Mediawiki search is pretty good, and google will crawl it, so they can
> be used as a secondary search tool.  :-)
> 
> > So, my vote would be to require a plain text format/template
> > that should be used with no Mediawiki markup.  The binding
> > would be posted on the wiki between <pre></pre> tags.
> >
> > The plain text will give some flexibility in how the binding
> > could be used in other contexts.
> 
> Personally, I like the idea of using some basic markup, whether it be
> mediawiki or something else.  Originally, I considered using gitwiki
> which stores everything in a git repo, and uses the markdown markup
> format.  I like the idea of anyone being able to clone the repo and
> editing it offline.  However, git-wiki is pretty immature, and I don't
> want to get into the business of maintaining wiki code.
> 
> By using some form of markup, it adds some level of context to the
> binding text which can be used to reformat into other forms, while
> still remaining readable in plain text (with the possible exception of
> tables).  Filters can easily be written to transform from one markup
> to another as needed.
> 
> Mediawiki is as readable as any, and it's got the advantage of a
> stable and well supported application behind it.  I've used mediawiki
> for a while now, and it's pretty much proven that it scales well, and
> does a good job of handling off-line edits.  Although I would agree
> that it makes sense to define a binding template and formating guide
> to keep things looking uniform and readable.

Ok.  I do think that the wiki formatting will keep things a bit more
readable via web browsers, which will be the primary way people
are reading this.

I do have a few ideas/suggestions for a binding template that I 
will post for comments soon.

> >> * Authors and reviews should work toward a consensus on 
> the binding.
> >> * When consensus is reached, ask one of the device tree binding
> >> maintainers mark the binding as 'approved'.
> >> * '''(TBD: who are the maintainers going to be?  How does someone
> >> contact the maintainers)'''
> >
> > To start with I think each company should designate a maintainer
> > for company-specific bindings.
> 
> s/designate/nominate/
> 
> Following the Linux lead, I want the caveat that a company doesn't
> automatically get to select the maintainer for their parts.  If
> someone shows competence and interest in a particular area, then I've
> got no problem with him or her being a maintainer regardless of who
> that person works for.  The reverse is also true; someone who hasn't
> already been involved with binding documentation and review should not
> get to be maintainer.

I agree.

Stuart

Re: new device tree binding review process idea

[Grant Likely]

On Thu, Apr 8, 2010 at 9:04 AM, Yoder Stuart-B08248
<B08248-KZfg59tc24xl57MIdRCFDg@public.gmane.org> wrote:
>> Mediawiki is as readable as any, and it's got the advantage of a
>> stable and well supported application behind it.  I've used mediawiki
>> for a while now, and it's pretty much proven that it scales well, and
>> does a good job of handling off-line edits.  Although I would agree
>> that it makes sense to define a binding template and formating guide
>> to keep things looking uniform and readable.
>
> Ok.  I do think that the wiki formatting will keep things a bit more
> readable via web browsers, which will be the primary way people
> are reading this.
>
> I do have a few ideas/suggestions for a binding template that I
> will post for comments soon.

Excellent!  Thanks.  I'll watch out for them.

g.