Re: [PATCH RFC] Add support for linux memfd_create syscall

["Michael Kerrisk (man-pages)" <mtk dot manpages at gmail dot com>]

Hi Carlos,

On 9 January 2015 at 17:17, Carlos O'Donell <carlos@redhat.com> wrote:
> On 01/09/2015 10:26 AM, Michael Kerrisk (man-pages) wrote:
>>>> @ Carlos: it *sounds* like you're saying that it's glibc policy that
>>>> an API must have tests and glibc manual documentation in order to get
>>>> admitted into the library. Is that really what you mean?
>>>
>>> There is no policy, and nothing is set in stone. However, *I* want
>>> a test written for this, and as a submitter you're looking for reviewer
>>> consensus. Would anybody really argue that we don't need tests in this
>>> day and age?
>>
>> I certainly would not.
>>
>> But, my question was a little tendentious. It seems the bar has been
>> rather lower for native glibc APIs in the past, with many of them not
>> getting documented. So one reading of your comment could have been:
>> we're imposing a higher bar on outsiders (i.e., APIs imported from the
>> Linux kernel). I don't imagine that's what you really mean, but when I
>> first read your comments I did a double take along those lines.
>
> The bar is the same for everyone, it's in the contribution checklist
> which must be followed by all developers. I did not intend my comments
> to be interpreted as an adoption of double standards for the community.

Fair enough. Probably it's all a matter of the fact that it used to be
that nobody was doing what you do now, and that's why I noticed it.

> Those that commit without updating both the manual and man pages are
> doing a serious disservice to our users and other developers. If I
> had reviewed those patches I would have also requested they create
> documentation.
>
> If you'd like some testimony about the tenacity of my documentation
> requests just ask Florian Weimer (Red Hat) about commit
> 585367266923156ac6fb789939a923641ba5aaf4 :-)

Okay ;-).

> In the end all I can do is lead by example.

Yes, and you set a good example.

>>> See step 6 in the contribution checklist:
>>>
>>> "6. Testing"
>>> "* Adding a test-case to the test suite may increase the likelihood
>>>    of acceptance of your patch. In some cases it may be necessary. "
>>> https://sourceware.org/glibc/wiki/Contribution%20checklist#Testing
>>>
>>> In this case I would really like to see a test case. It should not be
>>> too hard to write and I can help with the glibc esoterica if required.
>>
>> Sounds good.
>
> And to add to that:
>
> "4.2 Documentation"
> https://sourceware.org/glibc/wiki/Contribution%20checklist#Documentation
>
> Which also links to the Linux man-pages project :)


Yes, thanks for that.

>>>> FWIW, I've recently been doing heavy editing of David's man pages
>>>> patches. They're now in a much better shape for release, but there's
>>>> still a number of points I want to resolve before releasing them. In
>>>> the meantime, they are sitting in a branch at
>>>> http://git.kernel.org/cgit/docs/man-pages/man-pages.git/log/?h=draft_memfd_create
>>>> and I have just sent out a mail (linux-man@vger.kernel.org, lkml)
>>>> requesting some review of the pages.
>>>
>>> I'm not going to look at those in the event that I want to help
>>> draft the GFDL version of the glibc manual for the function.
>>> Though I'd hope David and you contribute your text to glibc for
>>> inclusion in some form in the manual.
>>
>> I could do that, but is it possible to do this without a CLA (e.g.,
>> placing into public domain, or disclaiming copyright, or some such)?
>> Thing is, I'm not a fan of CLAs.
>
> Please ask a lawyer.
>
> You can disclaim your changes.
>
> See:
> https://sourceware.org/glibc/wiki/Contribution%20checklist#FSF_copyright_Assignment
>
> The disclaimer request is here:
> http://git.savannah.gnu.org/cgit/gnulib.git/plain/doc/Copyright/request-disclaim.changes

Okay. I'd be okay with doing that. If you want that for the
memfd_create() material, let me know.

But, to take the larger point a little further. For system calls such
as memfd_create(), presumably the most that that glibc is going to do
is supply a wrapper and a header file with some declarations and
constants. Does the glibc project then really want to get into the
business of maintaining documentation for another project's APIs?
Somehow, that seems a little... odd. (Yes, I know glibc is exposing
the APIs, but in the end, it has fairly limited control over them.)

Cheers,

Michael