[openstack-dev] [Ironic] Driver documentation in Ironic

Ruby Loo rlooyahoo at gmail.com
Mon Oct 19 13:38:49 UTC 2015

Hi Ramesh,

On 15 October 2015 at 11:53, Ramakrishnan G <rameshg87.openstack at gmail.com>

> So what all are the problems ?
> 1) Ability to update the driver documentation not-related to Ironic easily
> without waiting.
> 2) To save some core reviewers time who might not be familiar with the
> hardware.
> To solve the actual problem of updating the documentation easily while
> keeping it in-tree, I checked with infra folks if a subset of a repository
> can be +2ed/+Aed by another group.  They confirmed it's not possible
> (unless there was a communication gap in that conversation, folks can
> correct me if I am wrong).
> The following are the options that I can think of to address this:
> 1) Easy approvals for patches solely related to driver documentation. Once
> the driver team feels the documentation is ready, it can be +Aed by a core
> team member skipping the normal process of review. Of course, fixing any
> comments that come by, but not waiting for the normal rule of 2x+2s.

To date, when there is a driver documentation patch that is submitted, does
the driver team review them? Are there past cases where this has occurred
and there wasn't any 'useful' feedback from other reviewers before it got
the +A?

> 2) A separate repository for driver documentation controller by driver
> developers (a bad idea ??)

> 3) Allow to push driver documentation to wiki for those who wish to.

My preference is for the driver documentation to be outside any ironic
repository that I feel responsible for reviewing. I.e., I want to reduce
the number of patches that need to be reviewed :) I would love if the
driver documentation was outside, reviewed by the driver folks (however
they want to review it) and their own tech writers or whatever.

I took a look at Jim's comments on that patch and I'll copy some of it here
(hope you don't mind Jim):


Totally opposed to documentation on the wiki. Docs should be reviewed
(anyone with an Launchpad account can edit the wiki without review).

Also, in-tree docs are so much prettier, and can be tied to a release if we
decide to do so. :)

If there's too much overhead with keeping docs in tree, let's solve *that*
problem rather than just removing the docs.


Ramesh -- assuming I'm the odd person out and most people want the
documentation in-tree, let's try to look at and address the overhead with
keeping docs in tree. Perhaps you could elaborate on the problems (the 2
points you mention in your email). Eg, do people feel like there are too
many nits or other unnecessary comments that cause too many revisions for
very-little-benefit, or that no one 'ever' looks at the patch, or that even
a 1-day delay in getting a patch merged is too long, or what?

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20151019/a2697f07/attachment.html>

More information about the OpenStack-dev mailing list