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

[Ruby Loo]

>
> 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.
>
>
I think the issue of updating documentation on stable branches goes beyond
driver docs. I question whether we should be bundling the release-related
documentation with the code if it is near impossible to update that
documentation after a branch is created. For example, we have links to
release-related documentation, but they aren't correct. We released 4.2.1
(on stable/liberty branch), and the release notes there [0] don't show
release information for 4.2.1. You have to go to master [1] to see it :-(

How do the other projects do it (correctly), or is ironic the only one so
far that has in-tree documentation? It seems that after a stable branch is
cut for (some) projects, the docs team has 1 month or so beyond that to get
the documentation out. It would be great if the docs we currently maintain
in-tree could follow a similar schedule. (And how does the doc team deal
with updates to documentation for prior releases?)

--ruby

[0] http://docs.openstack.org/developer/ironic/4.2.1/releasenotes/index.html
[1] http://docs.openstack.org/developer/ironic/releasenotes/index.html
__
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

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

[Wan-yen Hsu]

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

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

[Jim Rollenhagen]

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 

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

[Ruby Loo]

Hi Ramesh,

On 15 October 2015 at 11:53, Ramakrishnan G 
wrote:

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

To date, when there is a driver documentation patch that is submitted, does
the driver team review them? Are there past cases where this has occurred
and there wasn't any 'useful' feedback from other reviewers before it got
the +A?


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

My preference is for the driver documentation to be outside any ironic
repository that I feel responsible for reviewing. I.e., I want to reduce
the number of patches that need to be reviewed :) I would love if the
driver documentation was outside, reviewed by the driver folks (however
they want to review it) and their own tech writers or whatever.

I took a look at Jim's comments on that patch and I'll copy some of it here
(hope you don't mind Jim):

-

Totally opposed to documentation on the wiki. Docs should be reviewed
(anyone with an Launchpad account can edit the wiki without review).

Also, in-tree docs are so much prettier, and can be tied to a release if we
decide to do so. :)

If there's too much overhead with keeping docs in tree, let's solve *that*
problem rather than just removing the docs.

--

Ramesh -- assuming I'm the odd person out and most people want the
documentation in-tree, let's try to look at and address the overhead with
keeping docs in tree. Perhaps you could elaborate on the problems (the 2
points you mention in your email). Eg, do people feel like there are too
many nits or other unnecessary comments that cause too many revisions for
very-little-benefit, or that no one 'ever' looks at the patch, or that even
a 1-day delay in getting a patch merged is too long, or what?

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

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

[Ruby Loo]

Hi Wan-yen,

On 19 October 2015 at 01:46, Wan-yen Hsu  wrote:

>
>
>  I fully agreed with Ramesh.  There is a need for driver owners to be able
> to quickly update their driver’s document.  Particularly, vendor's drivers
> have strong
>

What do you mean by 'quickly'? Quicker than it has been in the past I
assume, but what time frame do you think is reasonable?


> dependencies on their platform’s firmware.  For instance, a new release of
> firmware may have impact on vendor’s driver and may require a specific
> firmware settings or some workaround in driver configuration.  Therefore
> driver owners need to be able to update their driver documents to reflect
> support of firmware versions or hardware platforms, document firmware
> issues that have impacts to the drivers, …etc.   Also, as more and more
> features added to the
>

Driver owners ARE able to update their driver documents by submitting
patches.


> drivers and some features are related, sometimes it requires restructuring
> of the document to make it easier for readers to follow and understand.  I
> would very much
>

If restructuring is needed to make the documentation better, I would
welcome that very much.


> like to get tech writers to help my driver’s document but with current
> document review process and release schedule, it’s just very hard to do.
> As the result, document quality
>
suffers.  I really wish that we can give driver owner’s
>

I don't understand this. If you cannot get tech writers to help with your
driver documentation and your doc quality suffers, how does giving the
driver owner (who presumably wrote the driver doc that is suffering) more
control help? The doc quality will still suffer, won't it?


> more control of their documents and be able to update their driver
> documents when needed.
>
>
>

Perhaps you could define what 'more control' means and how you feel like
you've been restricted from doing this in the past. That would make it
easier for me to try to help come up with something that can address this
issue.

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

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

[Monty Taylor]

On 10/19/2015 01:46 AM, Wan-yen Hsu wrote:

  I fully agreed with Ramesh.  There is a need for driver owners to be
able to quickly update their driver’s document.  Particularly, vendor's
drivers have strong dependencies on their platform’s firmware.  For
instance, a new release of firmware may have impact on vendor’s driver
and may require a specific firmware settings or some workaround in
driver configuration.  Therefore driver owners need to be able to update
their driver documents to reflect support of firmware versions or
hardware platforms, document firmware issues that have impacts to the
drivers, …etc.   Also, as more and more features added to the drivers
and some features are related, sometimes it requires restructuring of
the document to make it easier for readers to follow and understand.  I
would very much like to get tech writers to help my driver’s document
but with current document review process and release schedule, it’s just
very hard to do.  As the result, document quality suffers.  I really
wish that we can give driver owner’s more control of their documents and
be able to update their driver documents when needed.

  Among all 3 options listed below, I prefer 2 or 3. Please consider
these options.



I am neither Ironic core, nor a driver developer - however ...


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.


I like this one the best. It's easy to enable and needs no extra 
bureaucracy. In fact, it's a streamlining, which I think is good.



2) A separate repository for driver documentation controller  by driver



developers (a bad idea ??)


If you were going to make a docs repo outside of Ironic, I'd expect it 
to be under docs, and you'd have the same concern.



3) Allow to push driver documentation to wiki for those who  wish to.


I'm very much not a fan of this. We have a giant system for collecting 
and publishing code and documentation. Before we punt on that and just 
use a wiki for _some_ of the documentation (now meaning that docs are in 
two places) - let's just fix the social issue around it being hard for 
vendors to update their driver docs.



Thoughts ???



[0]https://review.openstack.org/#/c/225602/




__
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




__
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

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

[Jim Rollenhagen]

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

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

[Wan-yen Hsu]

 I fully agreed with Ramesh.  There is a need for driver owners to be able
to quickly update their driver’s document.  Particularly, vendor's drivers
have strong dependencies on their platform’s firmware.  For instance, a new
release of firmware may have impact on vendor’s driver and may require a
specific firmware settings or some workaround in driver configuration.
Therefore driver owners need to be able to update their driver documents to
reflect support of firmware versions or hardware platforms, document
firmware issues that have impacts to the drivers, …etc.   Also, as more and
more features added to the drivers and some features are related, sometimes
it requires restructuring of the document to make it easier for readers to
follow and understand.  I would very much like to get tech writers to help
my driver’s document but with current document review process and release
schedule, it’s just very hard to do.  As the result, document quality
suffers.  I really wish that we can give driver owner’s more control of
their documents and be able to update their driver documents when needed.



 Among all 3 options listed below, I prefer 2 or 3. Please consider these
options.



 Thanks!



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



>[0] https://review.openstack.org/#/c/225602/
__
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

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

[Ramakrishnan G]

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

[0] https://review.openstack.org/#/c/225602/

Regards,
Ramesh
__
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