[bpf-next,0/4] Convert filter.txt to RST

Hi,

This is my latest attempt at converting Documentation/filter.txt to RST
format.  Added to the CC list because of additional changes to
Documentation/userspace-api/seccomp_filter.rst

For reference this set is a progression of the follow sets (in order of
post date to LKML)

 1. [PATCH bpf-next 00/13] docs: Convert BPF filter.txt to RST
 2. [RFC bpf-next 0/3] docs: Convert filter.txt to RST
 3. [RFC bpf-next v2 0/3] docs: Convert filter.txt to RST

Sending this to BPF maintainers for hopeful inclusion in the bpf-next
tree.  As discussed on LKML this set does all the conversion in a single
patch.  This includes adding SPDX licence comments
(inc. seccomp_filter), adding RST labels, and updating references.

Please note this set adds three files to the MAINTAINERS file for the
BPF maintainers.  Is this rude?

Also this set adds a SPDX licence to all new files and also to
seccomp_filter.rst  I did this because checkpatch asked me to but I am
unsure on the protocol, is it acceptable to add a licence to
documentation that someone else wrote?

For the Record;

Daniel and Alexei, can I please have permission to add GPLv2+ to the BPF
docs?

Kees, Andy, and Drewry, can I please have permission to add GPLv2+ to
seccomp_filter.rst 

(added Cc: tag to patch 2 that adds the licence identifiers)

thanks,
Tobin.

Tobin C. Harding (4):
  docs: net: Fix various minor typos
  docs: Separate and convert filter.txt to RST
  docs: Judiciously use double ticks
  docs: Remove filter.txt from the tree

 Documentation/networking/filter.txt           | 1476 -----------------
 Documentation/userspace-api/cBPF.rst          |  432 +++++
 Documentation/userspace-api/eBPF.rst          | 1006 +++++++++++
 Documentation/userspace-api/index.rst         |    3 +
 .../userspace-api/seccomp_filter.rst          |   11 +
 Documentation/userspace-api/socket_filter.rst |  183 ++
 MAINTAINERS                                   |    4 +-
 7 files changed, 1638 insertions(+), 1477 deletions(-)
 delete mode 100644 Documentation/networking/filter.txt
 create mode 100644 Documentation/userspace-api/cBPF.rst
 create mode 100644 Documentation/userspace-api/eBPF.rst
 create mode 100644 Documentation/userspace-api/socket_filter.rst

On Thu, Aug 09, 2018 at 03:23:24PM +1000, Tobin C. Harding wrote:
> 
> Daniel and Alexei, can I please have permission to add GPLv2+ to the BPF
> docs?

kernel licensing is GPLv2 without +
every file (including docs) can potentially have a different
compatible license, but since they were developed
implicitly under v2 only you would need to get a buy-in from
all contributors before making such change.

On Wed, Aug 08, 2018 at 11:07:35PM -0700, Alexei Starovoitov wrote:
> On Thu, Aug 09, 2018 at 03:23:24PM +1000, Tobin C. Harding wrote:
> > 
> > Daniel and Alexei, can I please have permission to add GPLv2+ to the BPF
> > docs?
> 
> kernel licensing is GPLv2 without +

According to process/license-rules.rst

	    GPL-2.0+  :  GNU General Public License v2.0 or later

> every file (including docs) can potentially have a different
> compatible license, but since they were developed
> implicitly under v2 only you would need to get a buy-in from
> all contributors before making such change.

So if a file does not _explicitly_ state that it is under another
licence it is ok to add GPLv2?


thanks,
Tobin.

On 08/09/2018 09:27 AM, Tobin C. Harding wrote:
> On Wed, Aug 08, 2018 at 11:07:35PM -0700, Alexei Starovoitov wrote:
>> On Thu, Aug 09, 2018 at 03:23:24PM +1000, Tobin C. Harding wrote:
>>>
>>> Daniel and Alexei, can I please have permission to add GPLv2+ to the BPF
>>> docs?
>>
>> kernel licensing is GPLv2 without +
> 
> According to process/license-rules.rst
> 
> 	    GPL-2.0+  :  GNU General Public License v2.0 or later

Not really, please see the first three paragraphs of process/license-rules.rst.
The COPYING file of the kernel says that it's 'v2' and not 'v2 or later',
unless otherwise _explicitly_ noted. Given that and given there is no other
specific note in filter.txt, it would mean it's v2-only due to that rule.

>> every file (including docs) can potentially have a different
>> compatible license, but since they were developed
>> implicitly under v2 only you would need to get a buy-in from
>> all contributors before making such change.
> 
> So if a file does not _explicitly_ state that it is under another
> licence it is ok to add GPLv2?
> 
> 
> thanks,
> Tobin.
>

On Thu, Aug 09, 2018 at 10:24:54AM +0200, Daniel Borkmann wrote:
> On 08/09/2018 09:27 AM, Tobin C. Harding wrote:
> > On Wed, Aug 08, 2018 at 11:07:35PM -0700, Alexei Starovoitov wrote:
> >> On Thu, Aug 09, 2018 at 03:23:24PM +1000, Tobin C. Harding wrote:
> >>>
> >>> Daniel and Alexei, can I please have permission to add GPLv2+ to the BPF
> >>> docs?
> >>
> >> kernel licensing is GPLv2 without +
> > 
> > According to process/license-rules.rst
> > 
> > 	    GPL-2.0+  :  GNU General Public License v2.0 or later
> 
> Not really, please see the first three paragraphs of process/license-rules.rst.
> The COPYING file of the kernel says that it's 'v2' and not 'v2 or later',
> unless otherwise _explicitly_ noted. Given that and given there is no other
> specific note in filter.txt, it would mean it's v2-only due to that rule.

Thanks for clarifying.  My understanding is now; this is a case where
checkpatch is too verbose and we do not actually need to add a specific
license identifier to the documentation files (new or otherwise).  They
get an implicit GPLv2.

I'll remove the licences identifiers and re-spin.

thanks,
Tobin.

On Fri, 10 Aug 2018 11:46:36 +1000
"Tobin C. Harding" <me@tobin.cc> wrote:

> Thanks for clarifying.  My understanding is now; this is a case where
> checkpatch is too verbose and we do not actually need to add a specific
> license identifier to the documentation files (new or otherwise).  They
> get an implicit GPLv2.

The objective actually is to have SPDX tags in all files in the kernel.
That includes documentation, even though people, as always, care less
about the docs than they do the code.

As I understood it, the complaint with the tags you put in wasn't their
existence, it was your putting GPLv2+ rather than straight GPLv2.  In the
absence of information to the contrary, you really have to assume the
latter, since that's the overall license for the kernel.

Thanks,

jon

On Fri, Aug 10, 2018 at 5:57 AM Jonathan Corbet <corbet@lwn.net> wrote:
>
> The objective actually is to have SPDX tags in all files in the kernel.
> That includes documentation, even though people, as always, care less
> about the docs than they do the code.

right, but let's do that as a separate patch set.
In the current set I'd focus on reviewing the actual doc changes.
In particular completely removing
Documentation/networking/filter.txt
feels wrong, since lots of websites point directly there.
Can we have at least few words there pointing to new location?

On Fri, Aug 10, 2018 at 06:57:52AM -0600, Jonathan Corbet wrote:
> On Fri, 10 Aug 2018 11:46:36 +1000
> "Tobin C. Harding" <me@tobin.cc> wrote:
> 
> > Thanks for clarifying.  My understanding is now; this is a case where
> > checkpatch is too verbose and we do not actually need to add a specific
> > license identifier to the documentation files (new or otherwise).  They
> > get an implicit GPLv2.
> 
> The objective actually is to have SPDX tags in all files in the kernel.
> That includes documentation, even though people, as always, care less
> about the docs than they do the code.
>
> As I understood it, the complaint with the tags you put in wasn't their
> existence, it was your putting GPLv2+ rather than straight GPLv2.  In the
> absence of information to the contrary, you really have to assume the
> latter, since that's the overall license for the kernel.

Righto, thanks Jon.  GPLv0 tags going in for v3


	Tobin

On Fri, Aug 10, 2018 at 10:51:28AM -0700, Alexei Starovoitov wrote:
> On Fri, Aug 10, 2018 at 5:57 AM Jonathan Corbet <corbet@lwn.net> wrote:
> >
> > The objective actually is to have SPDX tags in all files in the kernel.
> > That includes documentation, even though people, as always, care less
> > about the docs than they do the code.
> 
> right, but let's do that as a separate patch set.
> In the current set I'd focus on reviewing the actual doc changes.
> In particular completely removing
> Documentation/networking/filter.txt
> feels wrong, since lots of websites point directly there.
> Can we have at least few words there pointing to new location?

Something like ...


------------ filter.txt

BPF documentation can now be found in the following places:

- Introduction to BPF (Linux Socket Filter) - Documentation/userspace-api/socket-filter.rst
- Classic BPF (cBPF) - Documentation/userspace-api/cBPF.rst
- Internal BPF (eBPF) - Documentation/userspace-api/eBPF.rst

- SECCOMP BPF - Documentation/userspace-api/seccomp_filter.rst

- BPF Design Q&A - Documentation/bpf/bpf_design_QA.rst
- BPF Development Q&A - Documentation/bpf/bpf_devel_QA.rst

-------------


Also this highlights that bpf/index.rst is not quite correct yet in this
set.  The Q&A files are indexed but not explicitly mentioned.  My
feeling is that bpf/index.rst should mirror the information above.

thanks,
Tobin.

On Sat, Aug 11, 2018 at 09:50:58PM +1000, Tobin C. Harding wrote:
> On Fri, Aug 10, 2018 at 10:51:28AM -0700, Alexei Starovoitov wrote:
> > On Fri, Aug 10, 2018 at 5:57 AM Jonathan Corbet <corbet@lwn.net> wrote:
> > >
> > > The objective actually is to have SPDX tags in all files in the kernel.
> > > That includes documentation, even though people, as always, care less
> > > about the docs than they do the code.
> > 
> > right, but let's do that as a separate patch set.
> > In the current set I'd focus on reviewing the actual doc changes.
> > In particular completely removing
> > Documentation/networking/filter.txt
> > feels wrong, since lots of websites point directly there.
> > Can we have at least few words there pointing to new location?
> 
> Something like ...
> 
> 
> ------------ filter.txt
> 
> BPF documentation can now be found in the following places:
> 
> - Introduction to BPF (Linux Socket Filter) - Documentation/userspace-api/socket-filter.rst
> - Classic BPF (cBPF) - Documentation/userspace-api/cBPF.rst
> - Internal BPF (eBPF) - Documentation/userspace-api/eBPF.rst

Internal ?
that was the name we used for may be a month many years ago.
Please use 'extended BPF' in new filter.txt and all other places.

since merge window is open the patches would need to wait until
bpf-next opens up in few weeks.

Thanks