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

["Carlos O'Donell" <carlos at redhat dot com>]

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.

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 :-)

In the end all I can do is lead by 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 :)

>>> 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

>> My apologies if any of this sounds cranky, I left my morning
>> coffee downstairs :-)
> 
> It's okay -- I hope you got your coffee by now ;-).

Coffee firmly in hand. I think I still sound cranky :-)

Cheers,
Carlos.