[Ksummit-discuss] Draft Agenda for the Kernel Summit

[Ksummit-discuss] Draft Agenda for the Kernel Summit

[Theodore Ts'o]

The following is a draft agenda for the Kernel Summit.

Please note that three are still a number of TBD slots, and there will
also be another room available for unconference topics.  The timeslots
are still largely arbitrary and subject to change.

Please comment and propose any requests you might have for schedule
changes, things that you would like to talk about, etc.

Thanks!

						- Ted


Tuesday
========

 9:00 Keynotes
10:25 Coffee Break 
10:55 Pulling away from the tracing ABI quicksand (Mattieu Desnoyer, Steve Rostedt)
11:45 Printk redesign (Petr Mladek & Steve Rostedt)
12:25 Lunch
14:05 Media Summit issues to discuss (Mauro Carvalho)
14:55 TBD
15:35 Coffee Break 
16:05 Getting better/supplementary error info to userspace (David Howells)
16:55 TBD

Onsite Attendee reception 5:35pm

Wednesday
=========

 9:00 Keynotes
10:15 Conversation with Linus
10:35 Coffee break
11:05 Improve regression tracking (Thorsten Leemuis)
11:55 Kselftest use-cases (Shuah Khan)
12:35 lunch
14:15 Kernel Security (James Morris)
15:05 TBD
15:45 Coffee break
16:15 TBD
17:05 TAB Elections

All-Attendee reception 6pm


Tech topics that were discussed, but it's not clear whether we have
focus / someone to organize:

* Mobile phones
* Improving Kconfig
* Any of the more technical topics that were proposed for
     maintainer summit, or if people want to do some pre-discussion
     beforehand

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[Konstantin Ryabitsev]

On Thu, Oct 12, 2017 at 08:15:34PM -0400, Theodore Ts'o wrote:
>The following is a draft agenda for the Kernel Summit.
>
>Please note that three are still a number of TBD slots, and there will
>also be another room available for unconference topics.  The timeslots
>are still largely arbitrary and subject to change.
>
>Please comment and propose any requests you might have for schedule
>changes, things that you would like to talk about, etc.

Ted:

If there is a 40-ish minute slot to talk about basic developer 
workstation security hygiene, I'm up for doing it. It would cover things 
like:

- PGP and ssh keys best practices
- Git and PGP signatures overview
- Safer browsing with firefox+firejail
- Security benefits of Wayland
- Q&A

Best,
-- 
Konstantin Ryabitsev
Director, IT Infrastructure Security
The Linux Foundation
Montréal, Québec

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[James Morris]

On Thu, 12 Oct 2017, Theodore Ts'o wrote:

> Wednesday
> =========
> 
>  9:00 Keynotes
> 10:15 Conversation with Linus
> 10:35 Coffee break
> 11:05 Improve regression tracking (Thorsten Leemuis)
> 11:55 Kselftest use-cases (Shuah Khan)
> 12:35 lunch
> 14:15 Kernel Security (James Morris)

Here's a preliminary agenda for the security session:

http://kernsec.org/wiki/index.php/Linux_Kernel_Summit_2017,_Security_Session

This agenda will likely evolve up until the day.


-- 
James Morris
<james.l.morris@oracle.com>

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[Mauro Carvalho Chehab]

Hi Ted,

Em Thu, 12 Oct 2017 20:15:34 -0400
Theodore Ts'o <tytso@mit.edu> escreveu:

> The following is a draft agenda for the Kernel Summit.
> 
> Please note that three are still a number of TBD slots, and there will
> also be another room available for unconference topics.  The timeslots
> are still largely arbitrary and subject to change.
> 
> Please comment and propose any requests you might have for schedule
> changes, things that you would like to talk about, etc.
> 
> Thanks!
> 
> 						- Ted
> 
> 
> Tuesday
> ========
> 
>  9:00 Keynotes
> 10:25 Coffee Break 
> 10:55 Pulling away from the tracing ABI quicksand (Mattieu Desnoyer, Steve Rostedt)
> 11:45 Printk redesign (Petr Mladek & Steve Rostedt)
> 12:25 Lunch
> 14:05 Media Summit issues to discuss (Mauro Carvalho)

The idea here were to have the media summit discussions as part of the
KS. We'll end by doing it on Friday. So, we can remove it as a topic.

-

Yet, as we'll now have an open slot, and we ended by not adding
documentation to the Maintainers Summit, if this would be OK for
Jonathan, I propose to take this slot to do some technical discuss
about documentation.

From my side, there are two topics related to documentation that
that could fit at the technical non-maintainers part of KS:


1) Grouping drivers documentation files

While working on media and input doc file conversion to ReST, and while
looking to other similar driver-specific subsystems, I found a problem
about how we gather driver documentation.

On a typical driver subsystem, we have different sorts of documentation:

	- uAPI;
	- subsystem's core kAPI;
	- driver's implementation:
	- driver's user-centric stuff (like driver's specific modprobe
	  parameters and explanation about how hardware features will
	  be visible on userspace);

The model that it was used with DocBook were to place the uAPI docs under
the driver API book, and the rest on plain files.

I believe that the main reason for it was technical: with the old building 
system, we needed a XML file in order to handle kernel-doc markups.
However, using XML for every single doc file was not too practical.

Now that all doc files can include kernel-doc markups, IMHO we could do
a better job organizing them.

2) Documentation conversion to ReST

We finally got rid of the DocBook documents, with were all converted
to ReST. So, now documentation outside kernel-doc source file markups
are all in plain text, either using a ReST compatible format or
using some other random format[1].

[1] On a patch series I wrote to convert Documentation/*.txt files
    to a common style, I found several documents using some other
    Markup language (Markdown, Twiki, media wiki, ...). I also
    found several documents that seemed to be created by cloning
    a documentation style that were presenting on other .txt files
    (probably some de-facto Kernel's own documentation style).

From maintainer's PoV, in order to make the Kernel documentation
coherent, we need to stick with just one format and ensure that 
all new documents should follow it (that's basically why I proposed
it as a theme for the Maintainers summit), using some tool to check
if those files are following the documentation style - perhaps adding
some logic at checkpatch.pl to call Sphinx if a text file is inside a
patch - letting Sphinx do the file validation. In other words, I still
think we should discuss it at the Maintainer's summit.

Yet, from technical standpoint, it makes sense to discuss about how should
we organize the files at Documentation/ that aren't currently included
into any existing book.

My proposal is to cleanup all Documentation/*.txt files, discarding
the ones that are too outdated up to a point where it won't make sense to
keep. The remaining files would be moved into a sub-directory,
renamed to *.rst and added into an existing book (or a new one).

Cheers,
Mauro

Re: [Ksummit-discuss] Documentation session (was: Draft Agenda for the Kernel Summit)

[Jonathan Corbet]

On Thu, 19 Oct 2017 04:35:01 -0700
Mauro Carvalho Chehab <mchehab@infradead.org> wrote:

> Yet, as we'll now have an open slot, and we ended by not adding
> documentation to the Maintainers Summit, if this would be OK for
> Jonathan, I propose to take this slot to do some technical discuss
> about documentation.
> 
> From my side, there are two topics related to documentation that
> that could fit at the technical non-maintainers part of KS:

I'd thought about trying to propose a documentation-oriented session, but
I've just not had the time to really even think about it.

> 1) Grouping drivers documentation files
> 
> While working on media and input doc file conversion to ReST, and while
> looking to other similar driver-specific subsystems, I found a problem
> about how we gather driver documentation.
> 
> On a typical driver subsystem, we have different sorts of documentation:
> 
> 	- uAPI;
> 	- subsystem's core kAPI;
> 	- driver's implementation:
> 	- driver's user-centric stuff (like driver's specific modprobe
> 	  parameters and explanation about how hardware features will
> 	  be visible on userspace);
> 
> The model that it was used with DocBook were to place the uAPI docs under
> the driver API book, and the rest on plain files.

I think, honestly, that media is about the only subsystem that put
UAPI-related stuff in DocBook, just FWIW.  The bulk of the user-space API
has no in-kernel documentation at all, of course.

> I believe that the main reason for it was technical: with the old building 
> system, we needed a XML file in order to handle kernel-doc markups.
> However, using XML for every single doc file was not too practical.
> 
> Now that all doc files can include kernel-doc markups, IMHO we could do
> a better job organizing them.

Well, I have been trying to push that way.  One of my biggest points has
been trying to separate the documentation by audience; somebody looking for
UAPI info or module parameters probably doesn't care about the in-kernel
interfaces.  It's surprising how much resistance I got on that at times,
though.

Beyond that, I'd been trying to resist the temptation to design the
documentation layout too much.  Whatever we come up with seems likely to be
wrong and require some reshuffling anyway.  We've never tried to pull all
of the kernel docs together into a coherent whole before.

> 2) Documentation conversion to ReST
> 
> We finally got rid of the DocBook documents, with were all converted
> to ReST. So, now documentation outside kernel-doc source file markups
> are all in plain text, either using a ReST compatible format or
> using some other random format[1].
> 
> [1] On a patch series I wrote to convert Documentation/*.txt files
>     to a common style, I found several documents using some other
>     Markup language (Markdown, Twiki, media wiki, ...). I also
>     found several documents that seemed to be created by cloning
>     a documentation style that were presenting on other .txt files
>     (probably some de-facto Kernel's own documentation style).
> 
> From maintainer's PoV, in order to make the Kernel documentation
> coherent, we need to stick with just one format and ensure that 
> all new documents should follow it (that's basically why I proposed
> it as a theme for the Maintainers summit), using some tool to check
> if those files are following the documentation style - perhaps adding
> some logic at checkpatch.pl to call Sphinx if a text file is inside a
> patch - letting Sphinx do the file validation. In other words, I still
> think we should discuss it at the Maintainer's summit.

Pushing for RST-compatible formatting makes sense, and I tend to do that
when I see docs posted.  I'm not convinced that we want to apply a lot of
force to get there, though, for not-yet-converted docs.  The whole idea is
for RST to win over on its merits so we don't get too much pushback; for
the most part, I think that's working.

> Yet, from technical standpoint, it makes sense to discuss about how should
> we organize the files at Documentation/ that aren't currently included
> into any existing book.
> 
> My proposal is to cleanup all Documentation/*.txt files, discarding
> the ones that are too outdated up to a point where it won't make sense to
> keep. The remaining files would be moved into a sub-directory,
> renamed to *.rst and added into an existing book (or a new one).

Mauro, when I see you actually wanting to discard an obsolete document I'm
going to fall out of my chair in shock :)

I do very much want to see the remaining documentation brought under the
RST umbrella.  To a great extent, I think it's going to involve working
with the relevant subsystem maintainers, one by one, and doing the
conversion, kerneldoc comment fixups, etc. in a way that doesn't create too
much trouble for them.  Perhaps a session next week could be a good start
on that.

Thanks,

jon

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[Theodore Ts'o]

On Fri, Oct 13, 2017 at 02:28:04PM -0400, Konstantin Ryabitsev wrote:
> Ted:
> 
> If there is a 40-ish minute slot to talk about basic developer workstation
> security hygiene, I'm up for doing it. It would cover things like:
> 
> - PGP and ssh keys best practices
> - Git and PGP signatures overview
> - Safer browsing with firefox+firejail
> - Security benefits of Wayland
> - Q&A

That sounds execellent, thanks!

							- Ted

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[Theodore Ts'o]

On Thu, Oct 19, 2017 at 01:12:27PM -0700, Mauro Carvalho Chehab wrote:
> > 14:05 Media Summit issues to discuss (Mauro Carvalho)  
> 
> The idea here were to have the media summit discussions as part of the
> KS. We'll end by doing it on Friday. So, we can remove it as a topic.
> 
> Yet, as we'll now have an open slot, and we ended by not adding
> documentation to the Maintainers Summit, if this would be OK for
> Jonathan, I propose to take this slot to do some technical discuss
> about documentation.

OK, sounds good.

						- Ted

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[Rafael J. Wysocki]

Hi Ted,

On Friday, October 13, 2017 2:15:34 AM CEST Theodore Ts'o wrote:
> The following is a draft agenda for the Kernel Summit.
> 
> Please note that three are still a number of TBD slots, and there will
> also be another room available for unconference topics.  The timeslots
> are still largely arbitrary and subject to change.
> 
> Please comment and propose any requests you might have for schedule
> changes, things that you would like to talk about, etc.

I haven't CCed you directly on my recent tech-topic message, so
let me repeat it below:

If this isn't too late, I'd like to put a PM topic on the agenda.

One problem basically is that runtime PM interacts with system-wide PM for
devices in ways that need to be taken care of.  The most common patterns are:

- What if a device is in runtime suspend before system suspend?  Can it
  remain suspended and under what conditions if so?

- Can devices be left in suspend when the system is resuming from
  system-wide suspend?

- Can driver runtime PM callbacks be used for system-wide PM too and to
  what extent?  If they can, how to make that happen?

We have tried to address these points in a couple of different ways so
far, but none of them is universal enough.  Moreover, one approach is
mostly for systems with PCI/ACPI and the other one is used on systems
without those and they both are not compatible.  That sort of didn't
matter until IP block sharing between vendors led to situations in
which one and the same driver is expected to work in both environments.

It would be good to have a common approach and IMO it should be based on
changing the PM core to help address the most common cases, so I posted
a set of patches to that end:

https://marc.info/?l=linux-kernel&m=150811822405206&w=2

and I'd like to have a discussion regarding that and it spans many
different subsystems potentially, so the KS seems to be the right venue
for that discussion to happen.

The second issue is that some bus types and quite a few drivers still use
legacy power management callbacks and I'd like to get rid of those at last,
first from the bus types and then from drivers too.  That's more of a
heads-up thing, but also possibly touches multiple places, so should be
suitable for a KS session as well.

At least Ulf is interested in this too, but it should be at least
tangentially interesting to other people at the KS too.

Thanks,
Rafael

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[Theodore Ts'o]

On Thu, Oct 12, 2017 at 08:15:34PM -0400, Theodore Ts'o wrote:
> Wednesday
> =========
> 
> 11:05 Improve regression tracking (Thorsten Leemhuis)

I'm finalizing the schedule for the kernel summit, and I wanted to
check in with you about whether (a) you think this topic is still a
useful one for us to have, and (b) whether you will be available / the
best person to lead the topic.

Thanks!!

					- Ted

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[Theodore Ts'o]

On Thu, Oct 12, 2017 at 08:15:34PM -0400, Theodore Ts'o wrote:
> 
> Wednesday
> =========
> 
> 11:55 Kselftest use-cases (Shuah Khan)

I'm finalizing the schedule for the kernel summit, and I wanted to
check in with you about whether (a) you think this topic is still a
useful one for us to have, and (b) whether you will be available / the
best person to lead the topic.

Thanks!!

						- Ted

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[Thorsten Leemhuis]

Lo! On 20.10.2017 04:18, Theodore Ts'o wrote:
> On Thu, Oct 12, 2017 at 08:15:34PM -0400, Theodore Ts'o wrote:
>> Wednesday
>> =========
>> 11:05 Improve regression tracking (Thorsten Leemhuis)
> 
> I'm finalizing the schedule for the kernel summit, and I wanted to
> check in with you about whether (a) you think this topic is still a
> useful one for us to have,

IMHO it definitely is. The mailing list discussion when I proposed that
session here shows there were a lot of people interested in regression
tracking or bug reporting/qa in general. And it was something that was
discussed in the past years on the kerenl or maintainers summit all the
time afaics from lwn.net reporting; sometimes it special sessions,
sometimes it just came up somewhere.

And FWIW: I just plan to speak a few minutes about my work and then go
over to a more discussion style format to ask people how to improve
things. From there we can also drift to some of the other topics that
came up on this list when I proposed the sessions (I wanted to mentioned
those anyway as a sort of reminder).

> and (b) whether you will be available / the
> best person to lead the topic.

Well, I'm the new kid in town, so maybe I'm not. Rafael (CCed) is
interested in this topic as well and is more experienced in the format.
I had thought about asking him to join me on stage anway if he wants, as
I expected him to be around. But if you think he's better suited for
leading this session I can hand over to him. no worries.

Ciao, Thorsten

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[Steven Rostedt]

On Thu, 12 Oct 2017 20:15:34 -0400
Theodore Ts'o <tytso@mit.edu> wrote:

> Tuesday
> ========

> 11:45 Printk redesign (Petr Mladek & Steve Rostedt)

Sergey needs to be part of this discussion too.

-- Steve

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[Rafael J. Wysocki]

On Friday, October 20, 2017 5:32:53 AM CEST Thorsten Leemhuis wrote:
> Lo! On 20.10.2017 04:18, Theodore Ts'o wrote:
> > On Thu, Oct 12, 2017 at 08:15:34PM -0400, Theodore Ts'o wrote:
> >> Wednesday
> >> =========
> >> 11:05 Improve regression tracking (Thorsten Leemhuis)
> > 
> > I'm finalizing the schedule for the kernel summit, and I wanted to
> > check in with you about whether (a) you think this topic is still a
> > useful one for us to have,
> 
> IMHO it definitely is. The mailing list discussion when I proposed that
> session here shows there were a lot of people interested in regression
> tracking or bug reporting/qa in general. And it was something that was
> discussed in the past years on the kerenl or maintainers summit all the
> time afaics from lwn.net reporting; sometimes it special sessions,
> sometimes it just came up somewhere.
> 
> And FWIW: I just plan to speak a few minutes about my work and then go
> over to a more discussion style format to ask people how to improve
> things. From there we can also drift to some of the other topics that
> came up on this list when I proposed the sessions (I wanted to mentioned
> those anyway as a sort of reminder).
> 
> > and (b) whether you will be available / the
> > best person to lead the topic.
> 
> Well, I'm the new kid in town, so maybe I'm not. Rafael (CCed) is
> interested in this topic as well and is more experienced in the format.
> I had thought about asking him to join me on stage anway if he wants, as
> I expected him to be around. But if you think he's better suited for
> leading this session I can hand over to him. no worries.

I'll be around, but I think that this should be your session. :-)

I can help with the content etc anyway, though.

Thanks,
Rafael

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[Shuah Khan]

On 10/19/2017 08:19 PM, Theodore Ts'o wrote:
> On Thu, Oct 12, 2017 at 08:15:34PM -0400, Theodore Ts'o wrote:
>>
>> Wednesday
>> =========
>>
>> 11:55 Kselftest use-cases (Shuah Khan)
> 
> I'm finalizing the schedule for the kernel summit, and I wanted to
> check in with you about whether (a) you think this topic is still a
> useful one for us to have, and (b) whether you will be available / the
> best person to lead the topic.
> 

Hi Ted,

Sorry - I have been traveling didn't get back to you earlier.
I haven't seen much response to my original posting, so I am
not very sure how useful people think this would be as a topic.

If you need to drop this in favor of another topic, it would be
fine.

thanks,
-- Shuah

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[James Bottomley]

On Fri, 2017-10-20 at 08:31 -0600, Shuah Khan wrote:
> On 10/19/2017 08:19 PM, Theodore Ts'o wrote:
> > 
> > On Thu, Oct 12, 2017 at 08:15:34PM -0400, Theodore Ts'o wrote:
> > > 
> > > 
> > > Wednesday
> > > =========
> > > 
> > > 11:55 Kselftest use-cases (Shuah Khan)
> > 
> > I'm finalizing the schedule for the kernel summit, and I wanted to
> > check in with you about whether (a) you think this topic is still a
> > useful one for us to have, and (b) whether you will be available /
> > the
> > best person to lead the topic.
> > 
> 
> Hi Ted,
> 
> Sorry - I have been traveling didn't get back to you earlier.
> I haven't seen much response to my original posting, so I am
> not very sure how useful people think this would be as a topic.
> 
> If you need to drop this in favor of another topic, it would be
> fine.

Actually, it would be really useful to do an overview for people who
run git trees of what resources are available to us for easy tree
testing.  Most people are aware of linux-next and 0day, but fewer
understand how to customise the tests of the latter and get email
failure reports on specific branches.  I suspect even fewer know how to
run their own CI based on something like kselftests or xfstests.

James

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[Joe Perches]

On Fri, 2017-10-20 at 02:04 -0400, Steven Rostedt wrote:
> On Thu, 12 Oct 2017 20:15:34 -0400
> Theodore Ts'o <tytso@mit.edu> wrote:
> 
> > Tuesday
> > ========
> > 11:45 Printk redesign (Petr Mladek & Steve Rostedt)
> 
> Sergey needs to be part of this discussion too.

Is there going to be any streaming of these discussions?

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[Shuah Khan]

On 10/20/2017 09:27 AM, James Bottomley wrote:
> On Fri, 2017-10-20 at 08:31 -0600, Shuah Khan wrote:
>> On 10/19/2017 08:19 PM, Theodore Ts'o wrote:
>>>
>>> On Thu, Oct 12, 2017 at 08:15:34PM -0400, Theodore Ts'o wrote:
>>>>
>>>>
>>>> Wednesday
>>>> =========
>>>>
>>>> 11:55 Kselftest use-cases (Shuah Khan)
>>>
>>> I'm finalizing the schedule for the kernel summit, and I wanted to
>>> check in with you about whether (a) you think this topic is still a
>>> useful one for us to have, and (b) whether you will be available /
>>> the
>>> best person to lead the topic.
>>>
>>
>> Hi Ted,
>>
>> Sorry - I have been traveling didn't get back to you earlier.
>> I haven't seen much response to my original posting, so I am
>> not very sure how useful people think this would be as a topic.
>>
>> If you need to drop this in favor of another topic, it would be
>> fine.
> 
> Actually, it would be really useful to do an overview for people who
> run git trees of what resources are available to us for easy tree
> testing.  Most people are aware of linux-next and 0day, but fewer
> understand how to customise the tests of the latter and get email
> failure reports on specific branches.  I suspect even fewer know how to
> run their own CI based on something like kselftests or xfstests.
> 

Awesome. I can go over how to and various use-cases and how I am using
kselftest for stable realease testing.

thanks,
-- Shuah

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[Theodore Ts'o]

On Fri, Oct 20, 2017 at 02:53:05AM +0200, Rafael J. Wysocki wrote:
> 
> I haven't CCed you directly on my recent tech-topic message, so
> let me repeat it below:
> 
> If this isn't too late, I'd like to put a PM topic on the agenda.

Sorry, I thought I had acked you earlier.  Sure, no problem, I'll add
a power management topic onto the agenda.

					- Ted

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[Theodore Ts'o]

On Fri, Oct 20, 2017 at 08:57:30AM -0700, Joe Perches wrote:
> On Fri, 2017-10-20 at 02:04 -0400, Steven Rostedt wrote:
> > On Thu, 12 Oct 2017 20:15:34 -0400
> > Theodore Ts'o <tytso@mit.edu> wrote:
> > 
> > > Tuesday
> > > ========
> > > 11:45 Printk redesign (Petr Mladek & Steve Rostedt)
> > 
> > Sergey needs to be part of this discussion too.
> 
> Is there going to be any streaming of these discussions?

Unfortunately, no, sorry.

For the technical topics, the primary issue is one of cost.

						- Ted

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[Rafael J. Wysocki]

On Friday, October 20, 2017 9:46:16 PM CEST Theodore Ts'o wrote:
> On Fri, Oct 20, 2017 at 02:53:05AM +0200, Rafael J. Wysocki wrote:
> > 
> > I haven't CCed you directly on my recent tech-topic message, so
> > let me repeat it below:
> > 
> > If this isn't too late, I'd like to put a PM topic on the agenda.
> 
> Sorry, I thought I had acked you earlier.  Sure, no problem, I'll add
> a power management topic onto the agenda.
> 

Thank you!

[Ksummit-discuss] Documentation session (was: Draft Agenda for the Kernel Summit)

[Mauro Carvalho Chehab]

Em Thu, 19 Oct 2017 04:35:01 -0700
Mauro Carvalho Chehab <mchehab@infradead.org> escreveu:

> Hi Ted,
> 
> Em Thu, 12 Oct 2017 20:15:34 -0400
> Theodore Ts'o <tytso@mit.edu> escreveu:

Not sure what happened, but I didn't receive the answers from this
e-mail (and not even my original one), although I'm seeing them
at:
	https://lists.linuxfoundation.org/pipermail/ksummit-discuss/2017-October/004876.html

So, I'm just copy-pasting Jon's answer and answering below and answering to
it. 

I'm also copying two other addresses, to be sure that I'll receive any
replies to it.

Ted,

I talked with Jon today, and he said that the time for this session is
not good for him, due to the Kernel panel at OSS.

On Oct 19 21:02:53 UTC 2017
Jonathan Corbet corbet at lwn.net wrote:

> On Thu, 19 Oct 2017 04:35:01 -0700
> Mauro Carvalho Chehab <mchehab at infradead.org> wrote:
> 
> > Yet, as we'll now have an open slot, and we ended by not adding
> > documentation to the Maintainers Summit, if this would be OK for
> > Jonathan, I propose to take this slot to do some technical discuss
> > about documentation.
> > 
> > From my side, there are two topics related to documentation that
> > that could fit at the technical non-maintainers part of KS:
> 
> I'd thought about trying to propose a documentation-oriented session, but
> I've just not had the time to really even think about it.

:-)

> 
> > 1) Grouping drivers documentation files
> > 
> > While working on media and input doc file conversion to ReST, and while
> > looking to other similar driver-specific subsystems, I found a problem
> > about how we gather driver documentation.
> > 
> > On a typical driver subsystem, we have different sorts of documentation:
> > 
> > 	- uAPI;
> > 	- subsystem's core kAPI;
> > 	- driver's implementation:
> > 	- driver's user-centric stuff (like driver's specific modprobe
> > 	  parameters and explanation about how hardware features will
> > 	  be visible on userspace);
> > 
> > The model that it was used with DocBook were to place the uAPI docs under
> > the driver API book, and the rest on plain files.
> 
> I think, honestly, that media is about the only subsystem that put
> UAPI-related stuff in DocBook, just FWIW.  The bulk of the user-space API
> has no in-kernel documentation at all, of course.

Yes, only media was having uAPI related documentation in DocBook. and most
has no in-kernel documentation :-)

There are some uAPI documentation at Documentation/ABI (that reminds the
patchset I wrote sometime ago to generate a book with those stuff).

But there are other subsystems have some uAPI documentation on text files.
I noticed that when I converted the input documentation :-)

There are other places with uAPI (and sysadmin) stuff on per-subsystem
documents, like, for example:

	Documentation/usb/usbmon.txt

> 
> > I believe that the main reason for it was technical: with the old building 
> > system, we needed a XML file in order to handle kernel-doc markups.
> > However, using XML for every single doc file was not too practical.
> > 
> > Now that all doc files can include kernel-doc markups, IMHO we could do
> > a better job organizing them.
> 
> Well, I have been trying to push that way.  One of my biggest points has
> been trying to separate the documentation by audience; somebody looking for
> UAPI info or module parameters probably doesn't care about the in-kernel
> interfaces.  It's surprising how much resistance I got on that at times,
> though.

Yeah, grouping documentation per audience is a good thing. However, 
identifying the audience may not be trivial.

To be clear about what I'm meaning here, my main concern is how to organize
driver documentation.

Right now, for most driver subsystem we're grouping documentation
altogether an a single driver's kAPI book.

Yet, the audience for a random driver subsystem (for instance input)
is likely different than the audience for another subsystem (like network).

In other words, for someone developing stuff for, let's say, the input
subsystem, it is a way more likely that it will likely 

Also, it is a way likely would be a way more likely that someone that reads a
Linux input uAPI to also read a Linux input kAPI than to read about the
network API.

So, grouping per-subsystem makes more sense, IMHO.

That's a side effect of grouping per-subsystem that sounds positive:
people may start from userspace at the initial chapters of the documentation,
and then goes deeper to "advanced" topics, e. g. kAPI. That way, we could
attract more Kernel developers long term.

> Beyond that, I'd been trying to resist the temptation to design the
> documentation layout too much.  Whatever we come up with seems likely to be
> wrong and require some reshuffling anyway.  We've never tried to pull all
> of the kernel docs together into a coherent whole before.

Yeah, I'm pretty sure it will take some time to organize. I won't doubt that
we may need to change things again on some future.

> 
> > 2) Documentation conversion to ReST
> > 
> > We finally got rid of the DocBook documents, with were all converted
> > to ReST. So, now documentation outside kernel-doc source file markups
> > are all in plain text, either using a ReST compatible format or
> > using some other random format[1].
> > 
> > [1] On a patch series I wrote to convert Documentation/*.txt files
> >     to a common style, I found several documents using some other
> >     Markup language (Markdown, Twiki, media wiki, ...). I also
> >     found several documents that seemed to be created by cloning
> >     a documentation style that were presenting on other .txt files
> >     (probably some de-facto Kernel's own documentation style).
> > 
> > From maintainer's PoV, in order to make the Kernel documentation
> > coherent, we need to stick with just one format and ensure that 
> > all new documents should follow it (that's basically why I proposed
> > it as a theme for the Maintainers summit), using some tool to check
> > if those files are following the documentation style - perhaps adding
> > some logic at checkpatch.pl to call Sphinx if a text file is inside a
> > patch - letting Sphinx do the file validation. In other words, I still
> > think we should discuss it at the Maintainer's summit.
> 
> Pushing for RST-compatible formatting makes sense, and I tend to do that
> when I see docs posted.  I'm not convinced that we want to apply a lot of
> force to get there, though, for not-yet-converted docs.  The whole idea is
> for RST to win over on its merits so we don't get too much pushback; for
> the most part, I think that's working.

Yeah, that's true. Yet, IMHO we should do some efforts for the stuff that
are used on other subsystems (like USB and core driver APIs).

If nobody steps up, I may likely do that for USB documents, if I lose
Internet connection and hardware access for some time (like while on some
conference or during Seasons).

> > Yet, from technical standpoint, it makes sense to discuss about how should
> > we organize the files at Documentation/ that aren't currently included
> > into any existing book.
> > 
> > My proposal is to cleanup all Documentation/*.txt files, discarding
> > the ones that are too outdated up to a point where it won't make sense to
> > keep. The remaining files would be moved into a sub-directory,
> > renamed to *.rst and added into an existing book (or a new one).
> 
> Mauro, when I see you actually wanting to discard an obsolete document I'm
> going to fall out of my chair in shock :)

Well, you complained to me a few times that I was converting obsolete
documents :-)

> I do very much want to see the remaining documentation brought under the
> RST umbrella.  To a great extent, I think it's going to involve working
> with the relevant subsystem maintainers, one by one, and doing the
> conversion, kerneldoc comment fixups, etc. in a way that doesn't create too
> much trouble for them.  Perhaps a session next week could be a good start
> on that.

Yeah, sure!

Cheers,
Mauro

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[Joe Perches]

On Fri, 2017-10-20 at 15:50 -0400, Theodore Ts'o wrote:
> On Fri, Oct 20, 2017 at 08:57:30AM -0700, Joe Perches wrote:
> > On Fri, 2017-10-20 at 02:04 -0400, Steven Rostedt wrote:
> > > On Thu, 12 Oct 2017 20:15:34 -0400
> > > Theodore Ts'o <tytso@mit.edu> wrote:
> > > 
> > > > Tuesday
> > > > ========
> > > > 11:45 Printk redesign (Petr Mladek & Steve Rostedt)
> > > 
> > > Sergey needs to be part of this discussion too.
> > 
> > Is there going to be any streaming of these discussions?
> 
> Unfortunately, no, sorry.
> 
> For the technical topics, the primary issue is one of cost.

I would appreciate a recap of the printk discussions

Re: [Ksummit-discuss] Draft Agenda for the Kernel Summit

[Jonathan Corbet]

On Mon, 30 Oct 2017 22:10:25 -0700
Joe Perches <joe@perches.com> wrote:

> I would appreciate a recap of the printk discussions

I'll get there, hopefully soon.

jon