Re: [RFC PATCH 0/5] DT binding documents using text markup

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 




On Tue, Sep 8, 2015 at 9:36 AM, Matt Porter <mporter@xxxxxxxxxxxx> wrote:
> On Tue, Sep 01, 2015 at 01:24:17PM -0500, Rob Herring wrote:
>> On Tue, Sep 1, 2015 at 1:03 PM, Tim Bird <tbird20d@xxxxxxxxx> wrote:
>> > On Tue, Sep 1, 2015 at 10:35 AM, Frank Rowand <frowand.list@xxxxxxxxx> wrote:
>> >> On 9/1/2015 10:14 AM, Tim Bird wrote:
>> >>> On Fri, Aug 28, 2015 at 10:13 AM, Matt Porter <mporter@xxxxxxxxxxxx> wrote:
>> >>
>> >> < snip >
>> >>
>> >>>>
>> >>>> But to answer your question, if we get a format I'll do
>> >>>> conversions and hope I'm not alone.
>> >>>
>> >>> I'm sure others will help out.  I will, and I'm pretty sure we can get
>> >>> some conversion sprints set up at conferences (I know I can set aside
>> >>> some time or resources at ELC in the spring - it might be too late for
>> >>> ELCE in October to set up a scheduled block of time, but we can start
>> >>> getting the word out.)  As I said in my other e-mail, one doesn't have
>> >>> to be a kernel coder to do this, and the conversions should be pretty
>> >>> straight-forward.
>> >>>  -- Tim
>> >>>
>> >>
>> >> A conversion sprint at ELCE sounds like a good idea if we can find a
>> >> good time to schedule it.  I can help, so there will be at least two
>> >> of us who can help people as they encounter issues.
>> >
>> > Even if we don't find a block of time, we can do something like
>> > announce a "contest", ask people to do something in their spare time,
>> > and find some way to get them a raffle ticket if they submit a patch
>> > with a conversion.  Then hold an extra prize drawing during the
>> > closing session, with just those raffle tickets, and give someone a
>> > nice award for contributing.  Of course, there's always the adage that
>> > you should be careful what you measure and reward...  We don't want a
>> > flood of crappy conversions, with a time constraint on the review.
>> > I'll think some more about this.  An alternative would be to have a
>> > contest announced ahead of the event, with enough time for people to
>> > submit and get reviewed.
>>
>> Sounds like a review nightmare. That's another reason why as much
>> automated conversion we can do, the better.
>
> I don't want to discount the value of interested people getting together
> f2f to review these and potentially clean them up for submission. That
> depends on what we thinking is the minimal "in progress" conversion
> that can be place upstream. i.e. is it simply compatible strings
> autoconverted to tags and the entire current document in comments?

That is sufficient for me (I reserve the right to change my mind).
Logistically, it needs to be a script that can be run before/during
the merge window and perhaps again after. I'd guess the long pole here
is how we validate the .yaml files.

>> > By the way - I presume the new docs will replace the existing ones,
>> > but I could imagine wanting to have them live side-by-side
>> > temporarily.  Any thoughts on this?  Will file name or location
>> > changes be allowed during the conversion?
>>
>> I proposed some ideas earlier in the thread. Either we can have both
>> side by side or do a mass conversion to YAML making the existing doc a
>> comment (add # prefix).
>>
>
> Were you thinking that this automated conversion would be sufficient
> for an initial commit? I'm not sure if I misunderstood in your separate
> comments and was looking at this as something that would be hand edited
> to move the existing doc (# prefix) into description tags where
> appropriate.

Yes, I think it is more important to have infrastructure in place to
enable others than how much is converted initially. Certainly any
changes based on existing docs will have to be manual, but we may be
able to do multiple passes of automated conversions. Sharing any
conversion scripts is important to enable others for that as well.

>> Any renames/moving should be separate (there's some clean-up I'd like
>> to there as well). Exact rules depend on the approach, but we need to
>> be able to tell which bindings conversions are not started, in
>> progress, or complete.
>
> If we add .yaml in place we can identify what's in progress by the fact
> that a .yaml exists with the same filename and then based on which
> tags have been populated (such as type: and constraints: not yet
> populated) then we know the state.

You mean keeping the .txt and .yaml until done? If we are copying in
the current doc, then I'd rather not do that. I don't think looking at
the tags will work as it would be hard to distinguish incomplete from
done. However, we could simply have an "in-progress" tag that is
removed when done (might as well take advantage of our new found
structured docs).

Rob
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Index of Archives]     [Device Tree Compilter]     [Device Tree Spec]     [Linux Driver Backports]     [Video for Linux]     [Linux USB Devel]     [Linux PCI Devel]     [Linux Audio Users]     [Linux Kernel]     [Linux SCSI]     [XFree86]     [Yosemite Backpacking]
  Powered by Linux