Re: [openstack-dev] [TripleO] Spec Template Change Proposal
On 21/05/14 22:56, James Slagle wrote: On Wed, May 21, 2014 at 4:37 PM, Jay Dobies jason.dob...@redhat.com wrote: Currently, there is the following in the template: Proposed change === [snip] Alternatives [snip] Security impact --- The unit tests assert the top and second level sections are standard, so if I add a section at the same level as Alternatives under Proposed Change, the tests will fail. If I add a third level section using ^, they pass. The problem is that you can't add a ^ section under Proposed Change. Sphinx complains about a title level inconsistency since I'm skipping the second level and jumping to the third. But I can't add a second-level section directly under Proposed Change because it will break the unit tests that validate the structure. The proposed change is going to be one of the beefier sections of a spec, so not being able to subdivide it is going to make the documentation messy and removes the ability to link directly to a portion of a proposed change. I propose we add a section at the top of Proposed Change called Overview that will hold the change itself. That will allow us to use third level sections in the change itself while still having the first and section section structure validated by the tests. I have no problem making the change to the templates, unit tests, and any existing specs (I don't think we have any yet), but before I go through that, I wanted to make sure there wasn't a major disagreement. I'm a bit ambivalent to be honest, but adding a section for Overview doesn't really do much IMO. Just give an overview in the first couple of sentences under Proposed Change. If I go back and add an Overview section to my spec in review, I'm just going to slap everything in Proposed Change into one Overview section :). To me, Work Items is where more of the details goes (which does support aribtrary subsections with ^^^). In general though I think that the unit tests are too rigid and pedantic. Plus, having to go back and update old specs when we make changes to unit tests seems strange. No biggie right now, but we do have a couple of specs in review. Unless we write the unit tests to be backwards compatible. This just feels a bit like engineering just for the sake of it. Maybe we need a spec on it :). I was a bit surprised to see that we don't have the Data Model section in our specs, and when I had one, unit tests failed. We actually do have data model stuff in Tuskar and our json structures in tripleo. You can blame me for that, when I created the repository I took the nova template and removed the sections I thought we're not relevant perhaps I was a little too aggressive. I got no problem if we want to add any of them back in. Looks like these are the sections I removed: Data model impact REST API impact Notifications impact I'd obviously forgotten about Tuskar, sorry. Anyway, just my $0.02. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [TripleO] Spec Template Change Proposal
Merging a few of the replies into a single response: I like all of this plan, except for the name Overview. To me, Overview suggests a high-level summary rather than being one of the beefier sections of a spec. Something like Detail or Detailed overview (because the low-level detail will come in the changes that implement the spec, not in the spec) seem like better descriptions of what we intend to have there. I didn't put much thought into the name, so Overview, Summary, Detail, etc. doesn't matter to me. If we agree to go down the route of a holder section here (as compared to loosening the validation), I'll poll for a better name. I'm a bit ambivalent to be honest, but adding a section for Overview doesn't really do much IMO. Just give an overview in the first couple of sentences under Proposed Change. If I go back and add an Overview section to my spec in review, I'm just going to slap everything in Proposed Change into one Overview section :). To me, Work Items is where more of the details goes (which does support aribtrary subsections with ^^^). That's actually my expectation, that everything currently in place gets slapped under Overview. The change is pretty much only to support being able to further break down that section while still leaving the existing level of validation in place. It's not so much organizational as it is to make sphinx happy. In general though I think that the unit tests are too rigid and pedantic. Plus, having to go back and update old specs when we make changes to unit tests seems strange. No biggie right now, but we do have a couple of specs in review. Unless we write the unit tests to be backwards compatible. This just feels a bit like engineering just for the sake of it. Maybe we need a spec on it :). I agree that it's possible I'll be back here in the next few days complaining that my problem description is too large and would benefit from subsections, which I couldn't currently add because they'd be second-level sections which are strictly enforced. I was a bit surprised to see that we don't have the Data Model section in our specs, and when I had one, unit tests failed. We actually do have data model stuff in Tuskar and our json structures in tripleo. You can blame me for that, when I created the repository I took the nova template and removed the sections I thought we're not relevant perhaps I was a little too aggressive. I got no problem if we want to add any of them back in. Looks like these are the sections I removed: Data model impact REST API impact Notifications impact I'd obviously forgotten about Tuskar, sorry. We just landed a change to permit the third level subsections, but the intent AIUI of requiring exact titles to constrain the expression space in the interests of clarity. We can (and should) add more standard sections as needed. I do like the idea of having these look consistent. I can work within the structure fine given that third-level subsections are permitted, but my issue is still that I have been treating the first section under Proposed Change as the meaty part of the change, which due to the lack of a second-level subsection doesn't let me add my own subsections. Given the feedback, there are a few approaches we can take: 1. Add a second-level subsection at the start of Proposed Change. This subsection will be the description of the actual change and adding in this will allow custom subsections to be permitted by the existing unit tests. 2. Reduce the validation to only enforce required sections but not barf on the addition of new ones. Somewhat tangential (but to address Slagle's concern) is the question of whether or not we need some sort of template version number to prevent having to update X many existing specs when changing the structure in the future. I feel like this is overkill and it's probably much simpler to settle on a Juno template in the very near future (selfishly, I say near to allow my own issue here to be addressed) and then only change the templates at new versions. Again, I'm probably overthinking things at this point, but just throwing it out there. Personally, my vote is for #1. Existing specs are simple to update, just slap the existing change under the new subsection and move on. For the naming of it, I'm fine with James P's suggestion of Detail. Then for K, we make any changes to the template based on our usage of it in Juno. It's like a scrum post mortem task for a giant 6 month sprint :) ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [TripleO] Spec Template Change Proposal
On Wed, May 21, 2014 at 4:37 PM, Jay Dobies jason.dob...@redhat.com wrote: Currently, there is the following in the template: Proposed change === [snip] Alternatives [snip] Security impact --- The unit tests assert the top and second level sections are standard, so if I add a section at the same level as Alternatives under Proposed Change, the tests will fail. If I add a third level section using ^, they pass. The problem is that you can't add a ^ section under Proposed Change. Sphinx complains about a title level inconsistency since I'm skipping the second level and jumping to the third. But I can't add a second-level section directly under Proposed Change because it will break the unit tests that validate the structure. The proposed change is going to be one of the beefier sections of a spec, so not being able to subdivide it is going to make the documentation messy and removes the ability to link directly to a portion of a proposed change. I propose we add a section at the top of Proposed Change called Overview that will hold the change itself. That will allow us to use third level sections in the change itself while still having the first and section section structure validated by the tests. I like all of this plan, except for the name Overview. To me, Overview suggests a high-level summary rather than being one of the beefier sections of a spec. Something like Detail or Detailed overview (because the low-level detail will come in the changes that implement the spec, not in the spec) seem like better descriptions of what we intend to have there. I have no problem making the change to the templates, unit tests, and any existing specs (I don't think we have any yet), but before I go through that, I wanted to make sure there wasn't a major disagreement. Thoughts? ___ 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] [TripleO] Spec Template Change Proposal
On Wed, May 21, 2014 at 4:37 PM, Jay Dobies jason.dob...@redhat.com wrote: Currently, there is the following in the template: Proposed change === [snip] Alternatives [snip] Security impact --- The unit tests assert the top and second level sections are standard, so if I add a section at the same level as Alternatives under Proposed Change, the tests will fail. If I add a third level section using ^, they pass. The problem is that you can't add a ^ section under Proposed Change. Sphinx complains about a title level inconsistency since I'm skipping the second level and jumping to the third. But I can't add a second-level section directly under Proposed Change because it will break the unit tests that validate the structure. The proposed change is going to be one of the beefier sections of a spec, so not being able to subdivide it is going to make the documentation messy and removes the ability to link directly to a portion of a proposed change. I propose we add a section at the top of Proposed Change called Overview that will hold the change itself. That will allow us to use third level sections in the change itself while still having the first and section section structure validated by the tests. I have no problem making the change to the templates, unit tests, and any existing specs (I don't think we have any yet), but before I go through that, I wanted to make sure there wasn't a major disagreement. I'm a bit ambivalent to be honest, but adding a section for Overview doesn't really do much IMO. Just give an overview in the first couple of sentences under Proposed Change. If I go back and add an Overview section to my spec in review, I'm just going to slap everything in Proposed Change into one Overview section :). To me, Work Items is where more of the details goes (which does support aribtrary subsections with ^^^). In general though I think that the unit tests are too rigid and pedantic. Plus, having to go back and update old specs when we make changes to unit tests seems strange. No biggie right now, but we do have a couple of specs in review. Unless we write the unit tests to be backwards compatible. This just feels a bit like engineering just for the sake of it. Maybe we need a spec on it :). I was a bit surprised to see that we don't have the Data Model section in our specs, and when I had one, unit tests failed. We actually do have data model stuff in Tuskar and our json structures in tripleo. Anyway, just my $0.02. -- -- James Slagle -- ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [TripleO] Spec Template Change Proposal
We just landed a change to permit the third level subsections, but the intent AIUI of requiring exact titles to constrain the expression space in the interests of clarity. We can (and should) add more standard sections as needed. -Rob On 22 May 2014 08:37, Jay Dobies jason.dob...@redhat.com wrote: Currently, there is the following in the template: Proposed change === [snip] Alternatives [snip] Security impact --- The unit tests assert the top and second level sections are standard, so if I add a section at the same level as Alternatives under Proposed Change, the tests will fail. If I add a third level section using ^, they pass. The problem is that you can't add a ^ section under Proposed Change. Sphinx complains about a title level inconsistency since I'm skipping the second level and jumping to the third. But I can't add a second-level section directly under Proposed Change because it will break the unit tests that validate the structure. The proposed change is going to be one of the beefier sections of a spec, so not being able to subdivide it is going to make the documentation messy and removes the ability to link directly to a portion of a proposed change. I propose we add a section at the top of Proposed Change called Overview that will hold the change itself. That will allow us to use third level sections in the change itself while still having the first and section section structure validated by the tests. I have no problem making the change to the templates, unit tests, and any existing specs (I don't think we have any yet), but before I go through that, I wanted to make sure there wasn't a major disagreement. Thoughts? ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev -- Robert Collins rbtcoll...@hp.com Distinguished Technologist HP Converged Cloud ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
