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