Re: updating the documentation

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Tue, Jul 18, 2017 at 9:03 PM, Gregory Farnum <gfarnum@xxxxxxxxxx> wrote:
> On Tue, Jul 18, 2017 at 6:51 AM, John Spray <jspray@xxxxxxxxxx> wrote:
>> On Wed, Jul 12, 2017 at 8:28 PM, Sage Weil <sweil@xxxxxxxxxx> wrote:
>>> On Wed, 12 Jul 2017, Patrick Donnelly wrote:
>>>> On Wed, Jul 12, 2017 at 11:29 AM, Sage Weil <sweil@xxxxxxxxxx> wrote:
>>>> > In the meantime, we can also avoid making the problem worse by requiring
>>>> > that all pull requests include any relevant documentation updates.  This
>>>> > means (1) helping educate contributors that doc updates are needed, (2)
>>>> > helping maintainers and reviewers remember that doc updates are part of
>>>> > the merge criteria (it will likely take a bit of time before this is
>>>> > second nature), and (3) generally inducing developers to become aware of
>>>> > the documentation that exists so that they know what needs to be updated
>>>> > when they make a change.
>>>>
>>>> There was a joke to add a bot which automatically fails PRs for no
>>>> documentation but I think there is an way to make that work in a
>>>> reasonable way. Perhaps the bot could simply comment on all PRs
>>>> touching src/ that documentation is required and where to look, and
>>>> then fails a doc check. A developer must comment on the PR to say it
>>>> passes documentation requirements before the bot changes the check to
>>>> pass.
>>>>
>>>> This addresses all three points in an automatic way.
>>>
>>> This is a great idea.  Greg brought up the idea of a bot but we
>>> didn't think of a "docs ok"-type comment to make it happy.
>>>
>>> Anybody interested in coding it up?
>>>
>>> Piotr makes a good point about config_opts.h, although that problem is
>>> about to go away (or at least change) with John's config update:
>>>
>>>         https://github.com/ceph/ceph/pull/16211
>>>
>>> (Config options will be documented in the code where the schema is
>>> defined, and docs.ceph.com .rst will eventually be auto-generated from
>>> that.)
>>
>>
>> Separate to the discussion of bots, here's a proposed change to the
>> SubmittingPatches.rst to formalize the expectation that submitters
>> make doc changes in their PRs.
>
> https://github.com/ceph/ceph/pull/16394 was meant to go here, I think. :)

Correct!  I like to throw the mistakes out there every once in a while
to check someone is paying attention :-)

John

> -Greg
>
>>
>> The twist here is that in addition to requiring submitters to make
>> changes, there is a responsibility on the component tech leads to
>> ensure there is a proper place for doc changes to go.  That means that
>> if someone comes with a change to a completely undocumented area of
>> functionality, then it is not the submitter's responsibility to create
>> the whole page just to note their small change (although it would
>> obviously be awesome if they did).
>>
>> Cheers,
>> John
>>
>>> sage
>>> --
>>> To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
>>> the body of a message to majordomo@xxxxxxxxxxxxxxx
>>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>> _______________________________________________
>> ceph-users mailing list
>> ceph-users@xxxxxxxxxxxxxx
>> http://lists.ceph.com/listinfo.cgi/ceph-users-ceph.com
_______________________________________________
ceph-users mailing list
ceph-users@xxxxxxxxxxxxxx
http://lists.ceph.com/listinfo.cgi/ceph-users-ceph.com



[Index of Archives]     [Information on CEPH]     [Linux Filesystem Development]     [Ceph Development]     [Ceph Large]     [Ceph Dev]     [Linux USB Development]     [Video for Linux]     [Linux Audio Users]     [Yosemite News]     [Linux Kernel]     [Linux SCSI]     [xfs]


  Powered by Linux