[RFC] In-tree documentation of driver deviations for Lucid and Maverick

Brad Figg brad.figg at canonical.com
Tue Nov 23 16:36:23 UTC 2010


On 11/23/2010 08:17 AM, Stefan Bader wrote:
> On 11/23/2010 05:08 PM, Brad Figg wrote:
>> On 11/23/2010 08:05 AM, Stefan Bader wrote:
>>> On 11/23/2010 04:58 PM, Brad Figg wrote:
>>>> On 11/23/2010 06:16 AM, Stefan Bader wrote:
>>>>> As discussed on UDS, we want to document driver deviations in a file, to make
>>>>> automated checks possible and to have the documentation even simpler to find.
>>>>>
>>>>> May proposal would be a file called debian.master/deviations.txt (which would
>>>>> allow to add additional debian.*/deviations.txt for topic branches).
>>>>>
>>>>> The contents are similar to the MAINTAINERS file. Attached are the prepared
>>>>> files for Lucid and Maverick.
>>>>>
>>>>> Comments? Objections? Modifications? Agreement?
>>>>>
>>>>> -Stefan
>>>>>
>>>>
>>>> Looks good. I do have one thing to consider. If you're going to use this as the
>>>> input for scripts, I'd suggest using json data format. This is easy to read text
>>>> and the best part is it easily loads into python as a dictionary or list or whatever
>>>> you want. Also it means that the name/value pairs can be readable strings instead
>>>> of single letter abbreviations. I use this format all the time now and have
>>>> convinced others to use it as well.
>>>>
>>> Well this is maybe simpler for python, but the target was to look like the
>>> maintainers file and this is what it looks like. Likely a bit harder on the
>>> parsing script but I am on that.
>>>
>>> -Stefan
>>>
>>>> Two entries would look something like:
>>>>
>>>> {
>>>>        "drm subsystem" : {
>>>>            "mailing list" : "kernel-team at lists.ubuntu.com",
>>>>            "repo"         : "git://git.kernel.org/pub/scm/linux/kernel/git/smb/linux-2.6.32.y-drm33.z.git",
>>>>            "files"        : [
>>>>                "drivers/gpu/drm/*",
>>>>                "include/drm/*"
>>>>            ],
>>>>            "comments"     : "Graphics bugs were claimed to be not fixable in 2.6.32. All upstream
>>>>        	                  had moved to 2.6.33 and abandoned 2.6.32.
>>>> 	                  The combined 2.6.32.y/DRM33.z tree is maintained as an upstream source
>>>> 	                  for Ubuntu and Debian."
>>>>        },
>>>>
>>>>        "sfc driver" : {
>>>>            "mailing list" : "kernel-team at lists.ubuntu.com",
>>>>            "repo"         : "git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-2.6.33.y.git",
>>>>            "files"        : ["drivers/net/sfc/*"],
>>>>            "comments"     : "Was requested in order to support newer servers and driver had changed
>>>> 	                  beyond a point to SRU it later.
>>>>                             "
>>>>        }
>>>>
>>>> }
>>>>
>>>
>>>
>>
>> So looking like the maintainers list was a hard requirement?
>>
> That sort of was said on UDS. And probably I am not in the group of people that
> got convinced to the JSON format either. To me the the format of the maintainers
> file looks much simpler and clean (and easier to type as me).
> Now if there is a great rising of people all in favour of JSON, I do not want to
> fight for it. Just that I like the other thing better. :)
>
> -Stefan
>

It was just a suggestion. Personally, I'm finding this a very convenient format and
it's easy to write:

     import json

     with open("data.json", "r") as f:
         data = json.load(f)


At this point "data" is now a standard python dictionary object. If you make changes
to it you can dump it back out as text with:

     print json.dumps(data, sort_keys=True, indent=4)


Brad
-- 
Brad Figg brad.figg at canonical.com http://www.canonical.com




More information about the kernel-team mailing list