Re: updating the documentation

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

 



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.

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



[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