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

Wan-yen Hsu wanyenhsu at gmail.com
Wed Oct 21 22:30:05 UTC 2015

As mentioned in the weekly IRC, 3rd-party vendor drivers are ranked lower
priority and therefore their code tend to merge at the late cycle of a
release.   Therefore,  it leads little time for driver author to submit
document and for upstream to review and approve the document.  So, as the
result, the 3r-party driver document could miss the release.  I don't think
the suggestion of code+document  submission and review will help
either.  IMO it will slow down review process as reviewers will need to
review documents for every feature comparing to one single document review
after all features are landed.  Hence I am concerned that it will slow down
the review process and make landing vendor's driver code even harder unless
upstream is willing to raise priority for vendor driver specs and code.
 Also,  some features are inter-related and can introduce document
inter-dependency if feature and documentation are bundled.   Moreover,
currently it is very difficult (if possible) to modify document after it
got merged into a stable tree.   Like defect in code, defects in document
exist.  For instance, some important configuration steps or pre-requisites
may be missing in the document.  Sometimes new firmware version has impact
on vendor's drivers and it will require changes in driver's pre-requisites
or configuration in order to work with the new firmware versions.  These
will require document changes in the stable branch.  Therefore, there is a
need for vendor driver author to make changes in stable branch to fix
document defects, document known firmware issues and resolutions, and
update information about supported firmware versions and hardware.   IMO,
Ramesh's option 2  & 3 will provide this kind of flexibility.  Option1 will
help driver document to land in time tor a release but won't enable changes
to the stable branch unless upstream allow driver authors to
self-approve document changes in the stable branch.    It would be my
preference, if PTL and upstream can work with infra to allow driver authors
to self-approve changes to the stable branch.   I am sincerely asking  for
help.  Any upstream effort to allow driver's document change in stable
branch and help driver document to land in new release in time will be very
much appreciated.

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20151021/e3937601/attachment.html>

More information about the OpenStack-dev mailing list