Open Stack

On Thu, Oct 15, 2015 at 09:23:18PM +0530, Ramakrishnan G wrote:
> Hi All,
> 
> This mail is related to driver-specific documentation in Ironic.
> 
> First a bit of context.  I work on iLO drivers in Ironic. Our team would
> like to document both Ironic driver related stuff (which is related to
> Ironic) and hardware related stuff like tested platforms, firmware
> information, firmware issues, etc (which is not related to Ironic) in the
> documentation. Today we keep it at two places - ironic related one in
> ironic tree and (ironic + non-ironic) related one in wiki. It's hard for
> both people who work on documentation and people who read this
> documentation to update/refer information in two places.  Hence we decided
> to raise the review [0] to move the content completely to wiki.  It got
> mixed response.  While some people are okay with it, but some others
> (including our ptl :)) feel it's worth putting it in-tree and try to
> address the problems.
> 
> 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.
> 
> 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.
> 
> Thoughts ???

We talked about this in our IRC meeting as well, and there isn't really
a good answer for "allow driver authors to merge their own docs ASAP".

I'd like to see some examples of docs patches that: 1) took too long to
merge, and 2) what problems that caused.

// jim