Open Stack

On Wed, Oct 21, 2015 at 03:30:05PM -0700, Wan-yen Hsu wrote:
> 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.
> Thanks!

There are two separate issues here:

1) Driver docs are hard to land quickly. There are a number of proposals
for fixing this; none of them are ideal. I still want to see hard
evidence of this with links to Gerrit before I continue thinking about
this.

2) Driver docs may not be backported to stable branches. This is a
stable maintenance policy, not an Ironic policy. This problem is
somewhat unique to Ironic as most major projects have deployer docs in
the Ops guide repo, rather than in the code repo. I'm going to chat with
some docs/stable maintenance people in Tokyo about this, however I also
encourage you to do the same.

// jim

> 
> 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

> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev