Open Stack

On Jan 20, 2017, at 9:41 AM, Sean Dague <sean at dague.net> wrote:
> 
> We released a new os-api-ref yesterday which includes a few
> enhancements, including the anchor links on the website working as
> expected now.
> 
> One of the things in there is a new warning when a parameter is used,
> and is not defined.
> 
> https://github.com/openstack/keystone/blob/bc8a145de14e455a2a73824e8a84d92ac27aae1c/api-ref/source/v2-ext/ksec2-admin.inc#L31
> - as an example
> 
> Which will generate an issue such as:
> 
> Warning, treated as error:
> /home/sdague/code/openstack/keystone/api-ref/source/api-ref/source/v2-ext/ksec2-admin.inc:112
> .rst:: WARNING: No path parameter ``userId`` found in rest_parameter stanza.
> 
> 

While I understand these are not desirable, is there a better way to communicate up-front that a potential gate breaking change is coming down the pipe? This change has impacted the ironic gate (https://bugs.launchpad.net/ironic/+bug/1658187), and we’re working now to resolve it, but simply a heads up a few days in advance could’ve prevented having a bunch of patches fail our api-ref jobs.

Thanks,
Jay Faulkner

> Long term, these really all need to be fixed, because this is specifying
> a parameter and giving the user no expectation about what it is and how
> it is used.
> 
> In the short term, if this is too hard for teams to address, remove the
> '-W' from the sphinx_build line in your api-ref section, then work
> through the warnings, and make warnings enforcing when done.
> 
> I've seen fails on keystone. But there may be fails other places as well.
> 
> Keystone fix is here - https://review.openstack.org/#/c/423387 as an
> example of what might be needed to move forward for projects.
> 
> 	-Sean
> 
> -- 
> Sean Dague
> http://dague.net
> 
> __________________________________________________________________________
> 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