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!
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-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
