Open Stack

> From: Steven Dake <sdake at redhat.com>
> To: "OpenStack Development Mailing List (not for usage questions)"
> <openstack-dev at lists.openstack.org>
> Date: 07/04/2014 21:45
> Subject: Re: [openstack-dev] [heat] Managing changes to the Hot
> Specification (hot_spec.rst)
>
> On 04/07/2014 11:01 AM, Zane Bitter wrote:
> > On 06/04/14 14:23, Steven Dake wrote:
> >> Hi folks,
> >>
> >> There are two problems we should address regarding the growth and
change
> >> to the HOT specification.
> >>
> >> First our +2/+A process for normal changes doesn't totally make sense
> >> for hot_spec.rst.  We generally have some informal bar for
controversial
> >> changes (of which changes to hot_spec.rst is generally considered:).
I
> >> would suggest raising the bar on hot_spec.rst to at-least what is
> >> required for a heat-core team addition (currently 5 approval votes).
> >> This gives folks plenty of time to review and make sure the heat core
> >> team is committed to the changes, rather then a very small 2 member
> >> subset.  Of course a -2 vote from any heat-core would terminate the
> >> review as usual.
> >>
> >> Second, There is a window where we say "hey we want this sweet new
> >> functionality" yet it remains "unimplemented".  I suggest we create
some
> >> special tag for these intrinsics/sections/features, so folks know they
> >> are unimplemented and NOT officially part of the specification until
> >> that is the case.
> >>
> >> We can call this tag something simple like
> >> "*standardization_pending_implementation* for each section which is
> >> unimplemented.  A review which proposes this semantic is here:
> >> https://review.openstack.org/85610
> >
> > This part sounds highly problematic to me.
> >
> > I agree with you and Thomas S that using Gerrit to review proposed
> > specifications is a nice workflow, even if the "proper" place to do
> > this is on the wiki and linked to a blueprint. I would probably go
> > along with everything you suggested provided that anything pending
> > implementation goes in a separate file or files that are _not_
> > included in the generated docs.
> >

Yeah, this would be optimal to be able to use gerrit for shaping it but
excluding it from the published docs.

> This is a really nice idea.  We could have a hot_spec_pending.rst which
> lists out the pending ideas so we can have a gerrit review of this doc.
> The doc wouldn't be generated into the externally rendered documentation.
>
> We could still use blueprints before/after the discussion is had on the
> hot_spec_pending.rst doc, but hot_spec_pending.rst would allow us to
> collaborate properly on the changes.

This could be a pragmatic option. What would be even better would be to
somehow flag sections in hot_spec.rst so they do not get included in the
published docs. This way, we would be able to continuesly merge changes
that come in while features are being implemented (typo fixes,
clarifications of existing public spec etc).

Has someone tried this out already? I read there is something like this for
rst:

.. options
   exclude <can this take sections?>

>
> The problem I have with blueprints is they suck for collaborative
> discussion, whereas gerrit rocks for this purpose.  In essence, I just
> want a tidier way to discuss the changes then blueprints provide.

Fully agree. Gerrit is nice for collaboration and enforces discipline.
While BPs and wiki are good but require everyone to really _be_
disciplined ;-)

>
> Other folks on this thread, how do you feel about this approach?
>
> Regards
> -steve
> > cheers,
> > Zane.
> >
> >> My goal is not to add more review work to people's time, but I really
> >> believe any changes to the HOT specification have a profound impact on
> >> all things Heat, and we should take special care when considering
these
> >> changes.
> >>
> >> Thoughts or concerns?
> >>
> >> Regards,
> >> -steve
> >>
> >>
> >> _______________________________________________
> >> OpenStack-dev mailing list
> >> OpenStack-dev at lists.openstack.org
> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> >
> >
> > _______________________________________________
> > OpenStack-dev mailing list
> > OpenStack-dev at lists.openstack.org
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>