Open Stack

I just learned that some projects are thinking about having the specs process be the channel for submitting new feature ideas, rather than registering blueprints. I must admit, that would be kind of nice because it would provide some much-needed structure around the triaging process.

I wonder if we can get some benefit out of the spec process while still keeping it light? The temptation will be to start documenting everything in excruciating detail, but we can mitigate that by codifying some guidelines on our wiki and baking it into the team culture.

What does everyone think?

From: Kurt Griffiths <kurt.griffiths at rackspace.com<mailto:kurt.griffiths at rackspace.com>>
Date: Tuesday, June 3, 2014 at 9:34 AM
To: OpenStack Dev <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
Subject: Re: [openstack-dev] [Marconi] Adopt Spec

I think it becomes more useful the larger your team. With a smaller team it is easier to keep everyone on the same page just through the mailing list and IRC. As for where to document design decisions, the trick there is more one of being diligent about capturing and recording the why of every decision made in discussions and such; gerrit review history can help with that, but it isn’t free.

If we’d like to give the specs process a try, I think we could do an experiment in j-2 with a single bp. Depending on how that goes, we may do more in the K cycle. What does everyone think?

From: Malini Kamalambal <malini.kamalambal at RACKSPACE.COM<mailto:malini.kamalambal at RACKSPACE.COM>>
Reply-To: OpenStack Dev <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
Date: Monday, June 2, 2014 at 2:45 PM
To: OpenStack Dev <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
Subject: Re: [openstack-dev] [Marconi] Adopt Spec

+1 – Requiring specs for every blueprint is going to make the development process very cumbersome, and will take us back to waterfall days.
I like how the Marconi team operates now, with design decisions being made in IRC/ team meetings.
So Spec might become more of an overhead than add value, given how our team functions.

'If' we agree to use Specs, we should use that only for the blue prints that make sense.
For example, the unit test decoupling that we are working on now – this one will be a good candidate to use specs, since there is a lot of back and forth going on how to do this.
On the other hand something like Tempest Integration for Marconi will not warrant a spec, since it is pretty straightforward what needs to be done.
In the past we have had discussions around where to document certain design decisions (e.g. Which endpoint/verb is the best fit for pop operation?)
Maybe spec is the place for these?

We should leave it to the implementor to decide, if the bp warrants a spec or not & what should be in the spec.


From: Kurt Griffiths <kurt.griffiths at rackspace.com<mailto:kurt.griffiths at rackspace.com>>
Reply-To: "OpenStack Development Mailing List (not for usage questions)" <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
Date: Monday, June 2, 2014 1:33 PM
To: "OpenStack Development Mailing List (not for usage questions)" <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
Subject: Re: [openstack-dev] [Marconi] Adopt Spec

I’ve been in roles where enormous amounts of time were spent on writing specs, and in roles where specs where non-existent. Like most things, I’ve become convinced that success lies in moderation between the two extremes.

I think it would make sense for big specs, but I want to be careful we use it judiciously so that we don’t simply apply more process for the sake of more process. It is tempting to spend too much time recording every little detail in a spec, when that time could be better spent in regular communication between team members and with customers, and on iterating the code (short iterations between demo/testing, so you ensure you are on staying on track and can address design problems early, often).

IMO, specs are best used more as summaries, containing useful big-picture ideas, diagrams, and specific “memory pegs” to help us remember what was discussed and decided, and calling out specific “promises” for future conversations where certain design points are TBD.

From: Malini Kamalambal <malini.kamalambal at RACKSPACE.COM<mailto:malini.kamalambal at RACKSPACE.COM>>
Reply-To: OpenStack Dev <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
Date: Monday, June 2, 2014 at 9:51 AM
To: OpenStack Dev <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
Subject: [openstack-dev] [Marconi] Adopt Spec

Hello all,

We are seeing more & more design questions in #openstack-marconi.
It will be a good idea to formalize our design process a bit more & start using spec.
We are kind of late to the party –so we already have a lot of precedent ahead of us.

Thoughts?

Malini

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140605/cd37b881/attachment.html>