Re: [openstack-dev] [heat] Managing changes to the Hot Specification (hot_spec.rst)
From: Steven Dake sd...@redhat.com To: OpenStack Development Mailing List (not for usage questions) openstack-dev@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@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [heat] Managing changes to the Hot Specification (hot_spec.rst)
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 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? Hi Steve, I'm -1 on merging the docs. Regardless of the warnings we put, people are going to be confused seeing features here that they can't use. There is also a huge changes that the implementation will change from the original doc, thus making us forced to update it if/when we merge. AFAIK gerrit is persistent, so we can keep the doc patch in it forever and link it in a blueprint. And merge the doc change alongside the implementation. Cheers, -- Thomas ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [heat] Managing changes to the Hot Specification (hot_spec.rst)
On Sun, Apr 06, 2014 at 11:23:28AM -0700, 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. I agree with Steve Baker here, I think the first step is to get an approved blueprint, with discussion before approval if needed, then the second step is the review (which should be primarily to evaluate the implemenation, not discuss the feature IMO). I do understand the motivation of what you're proposing, and in general I think it's already happening informally - I generally just +1 any change where I think it's controversial (or sometimes +2 with no +A if it's been posted for a while and looks nearly ready to merge) So how about: - All hot spec functional changes must have an associated blueprint - Where discussion is required, the blueprint can link a wiki page and we can discuss on the ML, during this phase the BP will be unapproved and in Discussion state for definition. - heat-core should never approve any functional changes to the hot spec without an *approved* associated blueprint - heat-core should never approve any functional change to the hot spec without positive feedback from a significant subset of the core team On the last point, I think it's largely down to common sense along with the existing process - if we've got feedback from many folks during the review iterations, I personally don't think we need to strictly enforce 5*+2's on the final patch, if e.g some minor change was needed in the final iteration but overall the change has had feedback indicating consensus. 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. IMO we should not merge documentation/spec changes before the implementation. There should be a series of patches implementing the feature, which ends with a documentation update to the spec and template guide. I think the place for documenting functionality which we want but is not yet implemented is the blueprint, or a wiki page linked from the blueprint. The review process should cater for this already IMO, if we only approve HOT patches with approved blueprints (which sufficiently define the new interface), and don't merge patches changing implementation affecting the HOT interfaces unless an associated docs/spec patch is also posted at the same time (or even the same patch if it's a simple change). Steve ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [heat] Managing changes to the Hot Specification (hot_spec.rst)
On Mon, Apr 07, 2014 at 09:30:50AM +0200, Thomas Spatzier wrote: From: Steve Baker sba...@redhat.com To: openstack-dev@lists.openstack.org Date: 06/04/2014 22:32 Subject: Re: [openstack-dev] [heat] Managing changes to the Hot Specification (hot_spec.rst) On 07/04/14 06: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 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? So in general, I think that might be a good approach, since doing this thru gerrit reviews seems to work pretty efficiently. However, we must be careful to really not confuse users, never forget to update the flags (probably by ensuring during in the feature implementation patches that the flag is removed), etc. How about we just use the existing blueprint approval process for changes to the HOT spec? The PTL can make the call whether the change can be approved by the PTL or whether it requires discussion and consensus first. I'm just a normal Heater (no core) so might not have the right level of insight into the process, but to me it looked like the relation between BPs and patches is not 100% strict. I.e. even if BPs exist but are in a somewhat abstract shape, changes get in, or changes get in without BPs. So for the BP-based approach to work, this would have to be handled more tightly. ... but I'm not suggesting unpragmatic development processes here, maybe just apply this to hot_spec? IMO patches which add or modify interfaces should always have a blueprint, and generally any patch fixing a user-visible problem should have a bug. Sometimes, if a patch is refactoring, doing cosmetic cleanups, or fixing a non-user-visible problem, I think it's fine to merge it without a BP or a bug, but if we're routinely merging user-visible changes without either, then we need to stop (I don't actually think we are btw..) So perhaps we just communicate a reminder to heat-core that they should pay particular attention to the hot spec (and any other user-visible changes such as additions to the API) to ensure changes are tracked appropriately in launchpad? Steve ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [heat] Managing changes to the Hot Specification (hot_spec.rst)
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. 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@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
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. 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. 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. 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@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [heat] Managing changes to the Hot Specification (hot_spec.rst)
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 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@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [heat] Managing changes to the Hot Specification (hot_spec.rst)
On 07/04/14 06: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 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? How about we just use the existing blueprint approval process for changes to the HOT spec? The PTL can make the call whether the change can be approved by the PTL or whether it requires discussion and consensus first. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
