[nova] "future" specs and blueprints
All- It seems like we don't have a great way of looking at a blueprint and saying, "this looks like a good idea, and yes we want to do it, but we're not going to be able to prioritize it for this release." Sometimes we just leave those blueprints "unspecified" and their specs stay open in limbo. And some blueprints we'll approve for the current series, and merge the spec under $current_cycle/approved, but not really intend to get the work completed. And at the end of the release, those pieces muddy our completion stats. It would be nice if those stats reflected only work we got done that we *intended* to get done. I'm not bringing this up just for the sake of making numbers pretty; it would just be nice to have a crisp picture of the work slated for the current release. And also a way for contributors to propose specs they *don't* intend for the current series, but still want to start discussing (I happen to know of at least one example of this for Train). And also a way to keep track of work we know we want to do eventually, just not now. === TL;DR >>> So I'd like to propose that we set up a "future" series in Launchpad, and a corresponding subdirectory in the specs repo. === TL;DR <<< The process would be pretty much as you would expect, including (but not limited to): - If we decide (e.g. at the PTG) that we like a spec that's proposed under $current/approved, but won't have time for it in the current series, we'll ask the author to move it to future/ and make sure the History section includes "$current: proposed and approved for 'future'". - If we decide in mid-release that we want to defer a blueprint, we can propose a patch to move it from $current/approved to future/ (including a redirect). - If a contributor wants to start work on a spec for a future release, they can propose it directly to the future/ path. - Every cycle when setting goals we can skim through the 'future' items to see if any should be pulled in. In which case we propose a patch to move the file from future/ to $current/approved (including a redirect) which we can fast-approve. - If we decide to flush a spec from 'future', we can move it to a 'rejected' (or 'abandoned'? bikeshed away) folder - but we can sort this part of the process out later. How do folks feel about this idea? -efried .
On Wed, Mar 27, 2019 at 3:47 PM Eric Fried <openstack@fried.cc> wrote:
All-
It seems like we don't have a great way of looking at a blueprint and saying, "this looks like a good idea, and yes we want to do it, but we're not going to be able to prioritize it for this release." Sometimes we just leave those blueprints "unspecified" and their specs stay open in limbo. And some blueprints we'll approve for the current series, and merge the spec under $current_cycle/approved, but not really intend to get the work completed. And at the end of the release, those pieces muddy our completion stats. It would be nice if those stats reflected only work we got done that we *intended* to get done.
I'm not bringing this up just for the sake of making numbers pretty; it would just be nice to have a crisp picture of the work slated for the current release. And also a way for contributors to propose specs they *don't* intend for the current series, but still want to start discussing (I happen to know of at least one example of this for Train). And also a way to keep track of work we know we want to do eventually, just not now.
=== TL;DR >>> So I'd like to propose that we set up a "future" series in Launchpad, and a corresponding subdirectory in the specs repo. === TL;DR <<<
The process would be pretty much as you would expect, including (but not limited to):
- If we decide (e.g. at the PTG) that we like a spec that's proposed under $current/approved, but won't have time for it in the current series, we'll ask the author to move it to future/ and make sure the History section includes "$current: proposed and approved for 'future'". - If we decide in mid-release that we want to defer a blueprint, we can propose a patch to move it from $current/approved to future/ (including a redirect). - If a contributor wants to start work on a spec for a future release, they can propose it directly to the future/ path. - Every cycle when setting goals we can skim through the 'future' items to see if any should be pulled in. In which case we propose a patch to move the file from future/ to $current/approved (including a redirect) which we can fast-approve. - If we decide to flush a spec from 'future', we can move it to a 'rejected' (or 'abandoned'? bikeshed away) folder - but we can sort this part of the process out later.
How do folks feel about this idea?
Isn't this what the backlog directory[0] is for? [0] http://git.openstack.org/cgit/openstack/nova-specs/tree/specs/backlog/approv... // jim
-efried .
Isn't this what the backlog directory[0] is for?
[0] http://git.openstack.org/cgit/openstack/nova-specs/tree/specs/backlog/approv...
Mm, thanks Jim. That appears to have been used for four months in 2015 (mitaka-ish?) New proposal: How do folks feel about using the `backlog` directory again? Presumably starting with scrubbing the four specs that are in it. -efried .
Le mer. 27 mars 2019 à 22:14, Eric Fried <openstack@fried.cc> a écrit :
Isn't this what the backlog directory[0] is for?
[0] http://git.openstack.org/cgit/openstack/nova-specs/tree/specs/backlog/approv...
Mm, thanks Jim.
That appears to have been used for four months in 2015 (mitaka-ish?)
New proposal: How do folks feel about using the `backlog` directory again? Presumably starting with scrubbing the four specs that are in it.
Well, we never said 'nope' to any proposal about providing a 'backlog" spec. It's just that maybe this directory wasn't known by more than the main contributors. If you want to communicate more for it, sure, maybe we should at least say it in https://docs.openstack.org/nova/latest/contributor/process.html FWIW, contributors can still still what a backlog spec is by http://specs.openstack.org/openstack/nova-specs/specs/backlog/index.html -Sylvain -efried
.
On Wed, Mar 27, 2019 at 10:10 PM, Eric Fried <openstack@fried.cc> wrote:
Isn't this what the backlog directory[0] is for?
[0] http://git.openstack.org/cgit/openstack/nova-specs/tree/specs/backlog/approv...
Mm, thanks Jim.
That appears to have been used for four months in 2015 (mitaka-ish?)
New proposal: How do folks feel about using the `backlog` directory again? Presumably starting with scrubbing the four specs that are in it.
I have no hard feelings about the backlog directory. We just need to make sure that we do some spring cleaning in that directory for time to time. There could be features that make sense today to put it to our backlog that will be invalidated by design decisions later. Also when movig a spec from backlog to approved directory we need to make sure to re-validate the assumptions in the spec based on the actual state of nova. Cheers, gibi
-efried .
On Thu, 2019-03-28 at 09:41 +0000, Balázs Gibizer wrote:
On Wed, Mar 27, 2019 at 10:10 PM, Eric Fried <openstack@fried.cc> wrote:
Isn't this what the backlog directory[0] is for?
[0] http://git.openstack.org/cgit/openstack/nova-specs/tree/specs/backlog/approv...
Mm, thanks Jim.
That appears to have been used for four months in 2015 (mitaka-ish?)
New proposal: How do folks feel about using the `backlog` directory again? Presumably starting with scrubbing the four specs that are in it.
I have no hard feelings about the backlog directory.
We just need to make sure that we do some spring cleaning in that directory for time to time. There could be features that make sense today to put it to our backlog that will be invalidated by design decisions later.
Also when movig a spec from backlog to approved directory we need to make sure to re-validate the assumptions in the spec based on the actual state of nova.
so this is on the ptg agenda as topic but since it relevant to this thread im not really opposed to the ideas put forward here but can we kill the nova-specs repo and just move it to an in tree specs folder in the nova repo. nova-specs-core now contains nova-core https://review.openstack.org/#/admin/groups/302,members so there is no real reason to keep it as a seperate repo. all people who are directly members of nova-specs-core are also nova cores and i dont think we plan to allow non nova cores approve nova-specs in the future so keeping nova-spec seperate form the nova code add little in my view and this will mean if implementation diverge or only partaily implment a spec they can correct that in the nova patch so that the two are never out of sync. i am personally not a fan of updating spec after they have been appoved but since that is something we allow it makes sense to me to make it easier too do.
Cheers, gibi
-efried .
On 2019-03-28 11:21:28 +0000 (+0000), Sean Mooney wrote: [...]
im not really opposed to the ideas put forward here but can we kill the nova-specs repo and just move it to an in tree specs folder in the nova repo. [...]
A few things you may want to consider with this plan: 1. You release and branch nova but not nova-specs, so moving your specs into nova means they will also now be released and branched as a part of nova. When specs change on master, will you backport those changes to the stable branch versions? Note that documentation is published independently for each branch so you'll potentially have different versions of the same spec published with documentation for each branch. 2. The Nova team has other deliverable repos besides nova itself, so if a spec is more relevant to another deliverable would it still reside in the nova repo, or elsewhere? 3. Keeping specs with the rest of your in-repository documentation makes it harder to use different Sphinx themes or configuration for specs as opposed to other docs. 4. Most (all?) OpenStack specs repos currently publish to specs.openstack.org rather than docs.openstack.org so this may make Nova's harder to find (or may make them easier to find if most people were expecting them to be in Nova's documentation, I can't really say what random readers expect if anything). -- Jeremy Stanley
On Thu, 2019-03-28 at 13:11 +0000, Jeremy Stanley wrote:
On 2019-03-28 11:21:28 +0000 (+0000), Sean Mooney wrote: [...]
im not really opposed to the ideas put forward here but can we kill the nova-specs repo and just move it to an in tree specs folder in the nova repo.
[...]
A few things you may want to consider with this plan:
1. You release and branch nova but not nova-specs, so moving your specs into nova means they will also now be released and branched as a part of nova. When specs change on master, will you backport those changes to the stable branch versions? Note that documentation is published independently for each branch so you'll potentially have different versions of the same spec published with documentation for each branch. if well we should never backport feature so the implies any intree changes to the specs are due to bugfixes. if the spec is updated in the same commit as the bug fix then when we backport it we ill also update it. i see this as an advangate as teh branched spec actully reflects what the current state is on the branch.
2. The Nova team has other deliverable repos besides nova itself, so if a spec is more relevant to another deliverable would it still reside in the nova repo, or elsewhere?
https://github.com/openstack/governance/blob/9caae68a2852e6263b9f44b3152c786... currntly nova deliverables are nova nova-spec ptynon-novaclient and os-vif os-vif does not ues spec unless we need to change somthing in nova itself. python-nova client does not use specs either as client updates are covered by the spec that intoduced the nova feature. so that just leave nova-spec and nova iteslf so i dont think this is an issue.
3. Keeping specs with the rest of your in-repository documentation makes it harder to use different Sphinx themes or configuration for specs as opposed to other docs.
i did not suggest keeping the spec with the rest of the documentation. as kolla ansible does an i think a few others i am suggeting we create a specs folder in the root of the nova repo. https://github.com/openstack/kolla-ansible/tree/master as a result there should be no issue with using different sphinx themes or configuration
4. Most (all?) OpenStack specs repos currently publish to specs.openstack.org rather than docs.openstack.org so this may make Nova's harder to find (or may make them easier to find if most people were expecting them to be in Nova's documentation, I can't really say what random readers expect if anything).
since this will not be part of the docs tree i dont see why we cant continue to publish the spec to specs.openstack.org as they wont be part of the docs.
just top posing on my side thread re moving the specs intree. we chatted a bit about this on the placement irc because i saw a similar conversation there and we remvoed this from the agenda for the PTG as the benifit of moving the specs with the history is not outwighed by the effort need to do the move. if people care about moving the specs in the future or feel the benifit is worth it then cool but im going to drop this side topic for now. On Thu, 2019-03-28 at 13:44 +0000, Sean Mooney wrote:
On Thu, 2019-03-28 at 13:11 +0000, Jeremy Stanley wrote:
On 2019-03-28 11:21:28 +0000 (+0000), Sean Mooney wrote: [...]
im not really opposed to the ideas put forward here but can we kill the nova-specs repo and just move it to an in tree specs folder in the nova repo.
[...]
A few things you may want to consider with this plan:
1. You release and branch nova but not nova-specs, so moving your specs into nova means they will also now be released and branched as a part of nova. When specs change on master, will you backport those changes to the stable branch versions? Note that documentation is published independently for each branch so you'll potentially have different versions of the same spec published with documentation for each branch.
if well we should never backport feature so the implies any intree changes to the specs are due to bugfixes. if the spec is updated in the same commit as the bug fix then when we backport it we ill also update it. i see this as an advangate as teh branched spec actully reflects what the current state is on the branch.
2. The Nova team has other deliverable repos besides nova itself, so if a spec is more relevant to another deliverable would it still reside in the nova repo, or elsewhere?
https://github.com/openstack/governance/blob/9caae68a2852e6263b9f44b3152c786...
currntly nova deliverables are
nova nova-spec ptynon-novaclient and os-vif
os-vif does not ues spec unless we need to change somthing in nova itself.
python-nova client does not use specs either as client updates are covered by the spec that intoduced the nova feature.
so that just leave nova-spec and nova iteslf so i dont think this is an issue.
3. Keeping specs with the rest of your in-repository documentation makes it harder to use different Sphinx themes or configuration for specs as opposed to other docs.
i did not suggest keeping the spec with the rest of the documentation. as kolla ansible does an i think a few others i am suggeting we create a specs folder in the root of the nova repo. https://github.com/openstack/kolla-ansible/tree/master as a result there should be no issue with using different sphinx themes or configuration
4. Most (all?) OpenStack specs repos currently publish to specs.openstack.org rather than docs.openstack.org so this may make Nova's harder to find (or may make them easier to find if most people were expecting them to be in Nova's documentation, I can't really say what random readers expect if anything).
since this will not be part of the docs tree i dont see why we cant continue to publish the spec to specs.openstack.org as they wont be part of the docs.
On 3/28/2019 4:21 AM, Sean Mooney wrote:
i am personally not a fan of updating spec after they have been appoved but since that is something we allow it makes sense to me to make it easier too do.
Ideally people wouldn't need to update specs after they are approved, but each spec varies in how much detail it has and those details can change once you get into code review, so sometimes it's good to update the spec later so it's not misleading if someone is reading the spec because there is otherwise a lack of docs about the feature. The best way to avoid having to update specs after approval IMO is to make sure when developing a feature you also have solid documentation outside of the spec to go with it, and sometimes getting developers to write useful feature documentation is like pulling teeth. -- Thanks, Matt
On Thu, 2019-03-28 at 06:47 -0700, Matt Riedemann wrote:
On 3/28/2019 4:21 AM, Sean Mooney wrote:
i am personally not a fan of updating spec after they have been appoved but since that is something we allow it makes sense to me to make it easier too do.
Ideally people wouldn't need to update specs after they are approved, but each spec varies in how much detail it has and those details can change once you get into code review, so sometimes it's good to update the spec later so it's not misleading if someone is reading the spec because there is otherwise a lack of docs about the feature. The best way to avoid having to update specs after approval IMO is to make sure when developing a feature you also have solid documentation outside of the spec to go with it, and sometimes getting developers to write useful feature documentation is like pulling teeth. ya i use specs as docs far more then i proably should as they often end up being the best developer focused docs we have.
my distaste form updating specs retroactivly only comes form the fact that we can endup looseing the original intent of the spec. but i agree that if something is only partially updated or we diverge for technicall reasons that only become apparent have accurate content in the spec is important. when we removed the devref section of the docs i think we lost somethign valuable that only the spec provide now. i know we have some dev docs in the contibutor and reference section of our docs but i think that our develop focused docs have regressed although our user and operator docs improved.
On 3/28/2019 7:07 AM, Sean Mooney wrote:
when we removed the devref section of the docs
Which part of the nova docs are you referring to specifically? As far as I know nothing has been removed, just re-arranged in Pike to follow a standard layout, i.e. old devref stuff is probably under /reference or /contributor. -- Thanks, Matt
On 3/28/2019 7:07 AM, Sean Mooney wrote:
when we removed the devref section of the docs
Which part of the nova docs are you referring to specifically? As far as I know nothing has been removed, just re-arranged in Pike to follow a standard layout, i.e. old devref stuff is probably under /reference or /contributor.
On Thu, 2019-03-28 at 07:42 -0700, Matt Riedemann wrote: they haven't been removed i just personally find it much harder to navigate the current structure to find the developer focused docs then it was previously. i always feel i can really write docs that are for developers only that explain how a feature works in a level of detail that endusers should not need to know. the cells docs https://github.com/openstack/nova/blob/stable/ocata/doc/source/cells.rst is one example of this. there is part of it in the admin guide https://github.com/openstack/nova/blob/stable/stein/doc/source/admin/cells.r... there is more info in the users guide https://github.com/openstack/nova/blob/stable/stein/doc/source/user/cells.rs... and https://github.com/openstack/nova/blob/stable/stein/doc/source/user/cellsv2-... cells are not user visable so i dont think most of that shoudl be under the user docs anyway but that a different issue. we nolonger have a singe doc that explains how cells v2 works. and there isnt anything in the contributor or reference folders. granted dan and others have done lots of good presentation on cellsv2 and we have way more docs on cells i belive then we used too so that all good but i often find my self thinking im glad we have specs to document developer focused info on feature because we dont have an intree docs location were we capture both reason/motivation and design constraints of a feature which is why i care alot about specs. that is what they provide that our user and admin facing docs dont capture and shouldn't as it for a different reader. anyway i didnt really want to rant but one of the reaons i personally dont write extensive dev docs outside of specs besides my spelling is i dont think there really is good place for them. i might consider reference more in the future.
On 3/28/2019 2:41 AM, Balázs Gibizer wrote:
I have no hard feelings about the backlog directory.
We just need to make sure that we do some spring cleaning in that directory for time to time. There could be features that make sense today to put it to our backlog that will be invalidated by design decisions later.
Also when movig a spec from backlog to approved directory we need to make sure to re-validate the assumptions in the spec based on the actual state of nova.
My thoughts exactly. -- Thanks, Matt
On 3/28/2019 2:41 AM, Balázs Gibizer wrote:
I have no hard feelings about the backlog directory.
We just need to make sure that we do some spring cleaning in that directory for time to time. There could be features that make sense today to put it to our backlog that will be invalidated by design decisions later.
Also when movig a spec from backlog to approved directory we need to make sure to re-validate the assumptions in the spec based on the actual state of nova.
My thoughts exactly.
I definitely agree that we need a higher bar for moving something to approved than just "we thought this was a good idea in the past." I feel the same way about re-approving specs cycle-to-cycle, for what it's worth. Using the backlog directory is fine, but I don't really see any point in doing that versus just leaving things as unmerged in Gerrit. I'm sure it matters to someone, but merging something that meets the "sure, we can put that in the backlog" bar at one point in time, which still needs to be re-reviewed in order to put it in the "okay we will actually let this in now" realm seems like not that useful of a dance to me. Assuming it solves some not-obvious-to-me problem, as long as we retain the re-review requirement then I guess I have no objection. --Dan
On Fri, Mar 29, 2019 at 5:37 AM Dan Smith <dms@danplanet.com> wrote:
I definitely agree that we need a higher bar for moving something to approved than just "we thought this was a good idea in the past." I feel the same way about re-approving specs cycle-to-cycle, for what it's worth.
Using the backlog directory is fine, but I don't really see any point in doing that versus just leaving things as unmerged in Gerrit. I'm sure it matters to someone, but merging something that meets the "sure, we can put that in the backlog" bar at one point in time, which still needs to be re-reviewed in order to put it in the "okay we will actually let this in now" realm seems like not that useful of a dance to me.
I agree with Dan here. From a contributor's perspective what does having a spec in the backlog directory give me? The promise of a future conversation about approval? I have that in the form of a new review already.
Assuming it solves some not-obvious-to-me problem, as long as we retain the re-review requirement then I guess I have no objection.
I think the problem the backlog directory solves is that it gives core a way to give a soft no that makes contributors less upset. I don't see a lot of value in that though. If the spec is a no then just say no. If its a big enough problem for the proposer they can hold their own patches or fork nova, much as people such as StarlingX, HP, and Rackspace Public Cloud did back in the day. Michael
On Mar 28, 2019, at 4:02 PM, Michael Still <mikal@stillhq.com> wrote:
I think the problem the backlog directory solves is that it gives core a way to give a soft no that makes contributors less upset. I don't see a lot of value in that though. If the spec is a no then just say no. If its a big enough problem for the proposer they can hold their own patches or fork nova, much as people such as StarlingX, HP, and Rackspace Public Cloud did back in the day.
IIRC, the backlog was for when people had an idea for a feature or improvement that had already been discussed and decided that it was potentially worthwhile, but was not going to be done in the current cycle. The benefit over putting it in the current cycle’s specs was that it didn’t attract reviewers and didn’t dilute the completed/proposed spec ratio, which some people were very concerned about. It also gave people a chance to “socialize” the idea without having to commit to creating a full spec. That said, it was never very active and if it were to disappear I don’t think it would make any difference. -- Ed Leafe
On Thu, 2019-03-28 at 16:28 -0500, Ed Leafe wrote:
On Mar 28, 2019, at 4:02 PM, Michael Still <mikal@stillhq.com> wrote:
I think the problem the backlog directory solves is that it gives core a way to give a soft no that makes contributors less upset. I don't see a lot of value in that though. If the spec is a no then just say no. If its a big enough problem for the proposer they can hold their own patches or fork nova, much as people such as StarlingX, HP, and Rackspace Public Cloud did back in the day.
IIRC, the backlog was for when people had an idea for a feature or improvement that had already been discussed and decided that it was potentially worthwhile, but was not going to be done in the current cycle. The benefit over putting it in the current cycle’s specs was that it didn’t attract reviewers and didn’t dilute the completed/proposed spec ratio, which some people were very concerned about. It also gave people a chance to “socialize” the idea without having to commit to creating a full spec. if we submitted code via the mailing list. which i hope we never do... that might be more useful but given we use gerrit i then to socialise ideas by either submiting a draft spec or writing it up in etherpad so and then posting to the mailing list or pinging people on irc for input.
That said, it was never very active and if it were to disappear I don’t think it would make any difference.
effectivly because gerrit reviews live forever, they provide much of the benifit however i do agree that review can get lost in gerrit and having a backlog of "we should proably do this at some point" reviews might be useful but people who work upstream across multiple release tend to bring up previous ideas again organically when we get to a point where its actully pratical to finally implement it. so if the backlog directory was to disappear i dont think it would have much effect in practice. with that said i did have a cases recently where one part of redhat that was not familar with nova sited a spec in our backlog folder as a depedency for a feature we were requesting, that was until we pointed out to them the spec in question ( https://github.com/openstack/nova-specs/blob/master/specs/backlog/approved/p...) was massively out of date and the problem descirbed in this spec is why placement now exits. looking at our current "backlog" https://github.com/openstack/nova-specs/tree/master/specs/backlog/approved i think they are all out of date.
-- Ed Leafe
On 3/29/2019 4:04 AM, Sean Mooney wrote:
looking at our current "backlog"https://github.com/openstack/nova-specs/tree/master/specs/backlog/approved i think they are all out of date.
Heh except for this one: https://review.openstack.org/#/c/635408/ -- Thanks, Matt
On Fri, 2019-03-29 at 07:19 -0700, Matt Riedemann wrote:
On 3/29/2019 4:04 AM, Sean Mooney wrote:
looking at our current "backlog"https://github.com/openstack/nova-specs/tree/master/specs/backlog/approved i think they are all out of date.
Heh except for this one: https://review.openstack.org/#/c/635408/ i was not aware that was being realistically progressed again given the push back this got in the past. which is why i assumed the idea was dead/out dated. ill add it to my review queue :)
Folks- The response to this has been mostly, "meh, if you like." Since I'm now the guy who gets to track the paperwork, I would like to give it a try for a cycle. If it doesn't work, or imposes too much process, or if people otherwise hate it, we can trash it, no harm no foul. To that end, I have proposed a patch [1] with some tooling and documentation. If you do nothing else, please read the (updated) section on "Backlog specifications" [2] and the (new) section on "Abandoning a specification" [3]. I have also eaten my own dogfood and proposed patches to abandon the four existing backlog specs [4]. I added those specs' original authors and assignees as reviewers (fwiw; some are surely inactive at this point). One of those had a Train spec that sounds eerily similar [5] so I suggested "move-spec" there. There's also a Train spec the author told me was intended for "future" [6] so I suggested that be moved to the backlog directory. I ask for help from nova-core to review and merge the tooling (including Mel's blueprint counting utility [7] which has been ready for a while) and the scrub patches. Moving forward, hopefully we can make it a recurring agenda item at PTGs to review backlog specs and promote, defer, or abandon them as appropriate. Thanks, efried [1] https://review.openstack.org/#/c/648800/ [2] http://logs.openstack.org/00/648800/3/check/openstack-tox-docs/e601952/html/... [3] http://logs.openstack.org/00/648800/3/check/openstack-tox-docs/e601952/html/... [4] https://review.openstack.org/#/q/topic:scrub-backlog-specs+(status:open+OR+s...) [5] https://review.openstack.org/#/c/635408/ [6] https://review.openstack.org/#/c/648665/ [7] https://review.openstack.org/#/c/581914/
On 4/1/2019 1:13 PM, Eric Fried wrote:
To that end, I have proposed a patch [1] with some tooling and documentation. If you do nothing else, please read the (updated) section on "Backlog specifications" [2] and the (new) section on "Abandoning a specification" [3].
I have also eaten my own dogfood and proposed patches to abandon the four existing backlog specs [4]. I added those specs' original authors and assignees as reviewers (fwiw; some are surely inactive at this point).
One of those had a Train spec that sounds eerily similar [5] so I suggested "move-spec" there.
There's also a Train spec the author told me was intended for "future" [6] so I suggested that be moved to the backlog directory.
I ask for help from nova-core to review and merge the tooling (including Mel's blueprint counting utility [7] which has been ready for a while) and the scrub patches.
Moving forward, hopefully we can make it a recurring agenda item at PTGs to review backlog specs and promote, defer, or abandon them as appropriate.
Just an update for other cores but I'm holding a +W on the bottom change in this series now [1] but will probably only wait until Friday (April 12) before approving. [1] https://review.openstack.org/#/c/648800/ -- Thanks, Matt
On Wed, Mar 27, 2019 at 04:10:09PM -0500, Eric Fried wrote: (Just catching up with this thread, post-PTO.) [...]
New proposal: How do folks feel about using the `backlog` directory again? Presumably starting with scrubbing the four specs that are in it.
Hi, I get a nagging feeling at the back of my head whenever I see specs in the "approved" directory for a given release, but they are not completed, or needs to be re-proposed for any number of good reasons. So yes, having this `specs/backlog/approved` does have a benefit (even if it is 'marginal') than "leaving things as unmerged in Gerrit", where every spec is a bland Gerrit URL, and their HTML renderings will have gotten purged. I agree with you that it gives a "crisper picture" of reality by not muddying the waters of what is actually completed. Plus it gives us a clean, rendered overview of what ideas we thought were worth pursuing (which, as Gibi noted, will be re-evaluated at the time of transition from "backlog" to "approved"). And, as you stated in the "Backlog specifications" section[2] in the README, it can act as a robust starting point for those (especially for experienced developers) who want to get involved with Nova. * * * On the topic of merging 'nova-specs' into 'nova' repo, Jeremy raised some really good points in his repsonse[2]. Unless I see his points addressed with compelling answers, I'd vote for keeping the 'nova-specs' repo separate. (I should admit that I don't know what was the original impetus for merging it into the 'nova' repo.) [1] http://logs.openstack.org/00/648800/3/check/openstack-tox-docs/e601952/html/... [2] http://lists.openstack.org/pipermail/openstack-discuss/2019-March/004314.htm... [...] -- /kashyap
On Wed, Mar 27, 2019 at 04:10:09PM -0500, Eric Fried wrote:
(Just catching up with this thread, post-PTO.)
[...]
New proposal: How do folks feel about using the `backlog` directory again? Presumably starting with scrubbing the four specs that are in it.
Hi,
I get a nagging feeling at the back of my head whenever I see specs in the "approved" directory for a given release, but they are not completed, or needs to be re-proposed for any number of good reasons.
So yes, having this `specs/backlog/approved` does have a benefit (even if it is 'marginal') than "leaving things as unmerged in Gerrit", where every spec is a bland Gerrit URL, and their HTML renderings will have gotten purged. well the html rendering are not really useful for reviewign a spec you might want to look at the near the end when the content is correct so that
On Tue, 2019-04-02 at 12:56 +0200, Kashyap Chamarthy wrote: the archive form looks nice but i would expects most peopel to read the rst directly.
I agree with you that it gives a "crisper picture" of reality by not muddying the waters of what is actually completed.
Plus it gives us a clean, rendered overview of what ideas we thought were worth pursuing (which, as Gibi noted, will be re-evaluated at the time of transition from "backlog" to "approved"). And, as you stated in the "Backlog specifications" section[2] in the README, it can act as a robust starting point for those (especially for experienced developers) who want to get involved with Nova.
* * *
On the topic of merging 'nova-specs' into 'nova' repo, Jeremy raised some really good points in his repsonse[2]. Unless I see his points addressed with compelling answers, I'd vote for keeping the 'nova-specs' repo separate. i tought i had fully adressed all of jeremy's questions in http://lists.openstack.org/pipermail/openstack-discuss/2019-March/004317.htm... i abandonded that direction simply because peopel seamed to feel the git subtree magic need to create a muli root git tree to extract
well actully completed specs get copied into the implemented directory. i dont think we tend to get a lot of future reaching specs. we get some that can not be completed due to developer or review bandwith in a singel cycle or that end up haveing depencies that mean the get punted to a follow up release. i have found most feature related to numa/nfv often take 2-3 cycles to fully land but that is generally not by intent. the spec directory form nova-specs and add it to nova was more hassel then it was worth. if i missed one of jeremy's point please respond but i didnt see any of the as a blocker for this work but perserving the history is something im willing to conceed is slightly more effort then i would like given the rewards.
(I should admit that I don't know what was the original impetus for merging it into the 'nova' repo.)
[1] http://logs.openstack.org/00/648800/3/check/openstack-tox-docs/e601952/html/... [2] http://lists.openstack.org/pipermail/openstack-discuss/2019-March/004314.htm...
[...]
So yes, having this `specs/backlog/approved` does have a benefit (even if it is 'marginal') than "leaving things as unmerged in Gerrit", where every spec is a bland Gerrit URL, and their HTML renderings will have gotten purged.
This. And hard to discover. Which of these (currently 64) unmerged nova specs [0] are (a) for train, (b) from a previous release but still viable for consideration, (c) dead? Today I can click through and look for file paths to determine (a) or not-(a); but I have to go full Sherlock to figure out (b) vs (c). Or count on the author to ask on IRC, add it to the PTG agenda, etc.
well the html rendering are not really useful for reviewign a spec you might want to look at the near the end when the content is correct so that the archive form looks nice but i would expects most peopel to read the rst directly.
Totally personal preference. I read the rendered version any time it's available. This is especially useful when things like seqdiag are used ([1] vs [2] if you please).
I agree with you that it gives a "crisper picture" of reality by not muddying the waters of what is actually completed. well actully completed specs get copied into the implemented directory.
Right, so the distinction between "never approved" and "approved for $release but not implemented" remains the same: unmerged gerrit review vs specs/$release/approved (but not specs/$release/implemented), respectively. What we're adding is "approved, but not for $release".
i dont think we tend to get a lot of future reaching specs.
Part of what pushed me over the edge to want to do this right now was [3] which I happened to know from talking to the author was intended for post-Train. But generally I agree, that's the exception rather than the rule. However...
we get some that can not be completed due to developer or review bandwith in a singel cycle
...this. We could make better use of the backlog directory to stage work we know is going to take multiple cycles.
On the topic of merging 'nova-specs' into 'nova' repo, Jeremy raised some really good points in his repsonse
One of the main original motivations was to remove the concept of separate "spec cores". This was already accomplished a couple of weeks ago by adding nova-core to nova-specs-core [4], and the remaining potential benefits were deemed not worth the trouble. -efried [0] https://review.openstack.org/#/q/project:openstack/nova-specs+status:open [1] http://specs.openstack.org/openstack/nova-specs/specs/rocky/approved/reshape... [2] https://review.openstack.org/#/c/572583/11/specs/rocky/approved/reshape-prov... [3] https://review.openstack.org/#/c/648665/ [4] https://review.openstack.org/#/admin/groups/302,members
On 2019-04-02 12:56:51 +0200 (+0200), Kashyap Chamarthy wrote: [...]
So yes, having this `specs/backlog/approved` does have a benefit (even if it is 'marginal') than "leaving things as unmerged in Gerrit", where every spec is a bland Gerrit URL, and their HTML renderings will have gotten purged. [...]
If the draft rendering has expired and you don't feel like generating one locally with tox (or even just by calling sphinx-build directly), you can also leave a "recheck" comment on the change and come back later. -- Jeremy Stanley
On Tue, Apr 02, 2019 at 02:41:49PM +0000, Jeremy Stanley wrote:
On 2019-04-02 12:56:51 +0200 (+0200), Kashyap Chamarthy wrote: [...]
So yes, having this `specs/backlog/approved` does have a benefit (even if it is 'marginal') than "leaving things as unmerged in Gerrit", where every spec is a bland Gerrit URL, and their HTML renderings will have gotten purged. [...]
If the draft rendering has expired and you don't feel like generating one locally with tox (or even just by calling sphinx-build directly), you can also leave a "recheck" comment on the change and come back later.
Ah, thanks for the tip. I keep forgetting that. (Still, it's inconvenient, as it breaks URLs. But it's not a show-stopper.) -- /kashyap
---- On Wed, 27 Mar 2019 14:45:02 -0500 Eric Fried <openstack@fried.cc> wrote ----
All-
It seems like we don't have a great way of looking at a blueprint and saying, "this looks like a good idea, and yes we want to do it, but we're not going to be able to prioritize it for this release." Sometimes we just leave those blueprints "unspecified" and their specs stay open in limbo. And some blueprints we'll approve for the current series, and merge the spec under $current_cycle/approved, but not really intend to get the work completed. And at the end of the release, those pieces muddy our completion stats. It would be nice if those stats reflected only work we got done that we *intended* to get done.
I'm not bringing this up just for the sake of making numbers pretty; it would just be nice to have a crisp picture of the work slated for the current release. And also a way for contributors to propose specs they *don't* intend for the current series, but still want to start discussing (I happen to know of at least one example of this for Train). And also a way to keep track of work we know we want to do eventually, just not now.
=== TL;DR >>> So I'd like to propose that we set up a "future" series in Launchpad, and a corresponding subdirectory in the specs repo. === TL;DR <<<
The process would be pretty much as you would expect, including (but not limited to):
- If we decide (e.g. at the PTG) that we like a spec that's proposed under $current/approved, but won't have time for it in the current series, we'll ask the author to move it to future/ and make sure the History section includes "$current: proposed and approved for 'future'". - If we decide in mid-release that we want to defer a blueprint, we can propose a patch to move it from $current/approved to future/ (including a redirect).
Thanks for bringing this up. What will be the conditions or criteria of the above two scenarios? - Review bandwidth? - Author (contributors) wish not to complete the code in the cycle when he/she is proposing the spec for? I mean do we have any scenario where spec author says "please approve my spec in this cycle but I will not start the code in this cycle so consider this a future spec" - Technical scope etc ? - Anything else ? IMO, the first two scenarios should not be the reason to ask people to propose your spec in future/ dir. For other scenarios, we should clearly say "NO: as of now due to xyz reason so rejected or suggestion for repropose" etc. future/ dir idea is good but main challenge it can face is "how many people going to review the future/ items' because I feel everyone is so busy with their current assignments.
- If a contributor wants to start work on a spec for a future release, they can propose it directly to the future/ path.
+1, this is a nice idea to start the early discussion/feedback etc. -gmann
- Every cycle when setting goals we can skim through the 'future' items to see if any should be pulled in. In which case we propose a patch to move the file from future/ to $current/approved (including a redirect) which we can fast-approve. - If we decide to flush a spec from 'future', we can move it to a 'rejected' (or 'abandoned'? bikeshed away) folder - but we can sort this part of the process out later.
How do folks feel about this idea?
-efried .
Apologies for top-posting, etc etc I'd like to mention something the Swift team introduced back in 2016 and has been using quite successfully ever since. After trying both blueprints and specs, we have settled on our ideas wiki page. Basically, if you've got an idea, write it down and link to it. I'll let the original email do more of the explaining: http://lists.openstack.org/pipermail/openstack-dev/2016-May/094026.html Swift's ideas page is at https://wiki.openstack.org/wiki/Swift/ideas --John On 27 Mar 2019, at 12:45, Eric Fried wrote:
All-
It seems like we don't have a great way of looking at a blueprint and saying, "this looks like a good idea, and yes we want to do it, but we're not going to be able to prioritize it for this release." Sometimes we just leave those blueprints "unspecified" and their specs stay open in limbo. And some blueprints we'll approve for the current series, and merge the spec under $current_cycle/approved, but not really intend to get the work completed. And at the end of the release, those pieces muddy our completion stats. It would be nice if those stats reflected only work we got done that we *intended* to get done.
I'm not bringing this up just for the sake of making numbers pretty; it would just be nice to have a crisp picture of the work slated for the current release. And also a way for contributors to propose specs they *don't* intend for the current series, but still want to start discussing (I happen to know of at least one example of this for Train). And also a way to keep track of work we know we want to do eventually, just not now.
=== TL;DR >>> So I'd like to propose that we set up a "future" series in Launchpad, and a corresponding subdirectory in the specs repo. === TL;DR <<<
The process would be pretty much as you would expect, including (but not limited to):
- If we decide (e.g. at the PTG) that we like a spec that's proposed under $current/approved, but won't have time for it in the current series, we'll ask the author to move it to future/ and make sure the History section includes "$current: proposed and approved for 'future'". - If we decide in mid-release that we want to defer a blueprint, we can propose a patch to move it from $current/approved to future/ (including a redirect). - If a contributor wants to start work on a spec for a future release, they can propose it directly to the future/ path. - Every cycle when setting goals we can skim through the 'future' items to see if any should be pulled in. In which case we propose a patch to move the file from future/ to $current/approved (including a redirect) which we can fast-approve. - If we decide to flush a spec from 'future', we can move it to a 'rejected' (or 'abandoned'? bikeshed away) folder - but we can sort this part of the process out later.
How do folks feel about this idea?
-efried .
participants (13)
-
Balázs Gibizer
-
Dan Smith
-
Ed Leafe
-
Eric Fried
-
Ghanshyam Mann
-
Jeremy Stanley
-
Jim Rollenhagen
-
John Dickinson
-
Kashyap Chamarthy
-
Matt Riedemann
-
Michael Still
-
Sean Mooney
-
Sylvain Bauza