[openstack-dev] [Ironic] Driver documentation in Ironic
jim at jimrollenhagen.com
Mon Oct 19 18:07:50 UTC 2015
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  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
> 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.
More information about the OpenStack-dev