Writing TripleO Specs

I was recently copied on an email from a team with a lot of new contributors to TripleO that was wondering if there was any sort of tips or guidelines for writing specs. My initial reaction was "The spec templates tell you how to write them." Then I realized that if you haven't ever written a spec before you may not know that. So, with that said, here are some of my thoughts on spec writing:

Disclaimer: These are my thoughts and opinions only. This is not endorsed by TripleO or anyone else in the OpenStack community. I'm just writing it in the hopes that it will be helpful.

The spec templates have guidelines on what to include

As I noted above, every project that uses specs has a template to start with. For example, this is TripleO's template. For each section that needs to be filled out there is some text that explains what should go in that section. As you fill out the spec you delete the help text and replace it with your own content.

When in TripleO, do as the owls do

(the TripleO logo is an owl, in case that doesn't make sense to you)

As with many things, it can be very helpful to look at what has been done in the past for a project. Read accepted TripleO specs and see what kind of content they had. This isn't a 100% accurate way to find out what the project wants, but it's a start.

TripleO is bad at reviewing specs

Sad, but true. You're probably going to have to ping people, maybe multiple times, to get them to review. Yes, this is indicative of a systemic problem and we're trying to address it, but this is the current reality. If possible, try to ping people who are in some way relevant to your spec. Pinging a UI core to review a networking spec probably won't help (unless it's a UI networking spec, of course ;-).

Don't get caught up in details

Specs are for defining a direction, not an implementation. For example, when discussing your test plan it would be sufficient to say "Tests for this feature will be added to the OVB HA job." You don't need to list the test files that you're going to add/change or anything like that. The goal here is to ensure some thought is given to each of the areas listed in the spec template, not to figure out every detail of the implementation.

TripleO also has policy specs

This is not unique to TripleO, but I don't know that every project does this. TripleO has recorded a number of policy specs that may be useful to read for all TripleO contributors.

Length

As a rule of thumb, most of my specs end up at around 200 lines or less. This is not to say your spec should absolutely be under 200 lines when complete, but if you're at 500 lines it may be indicative that you've gone too detailed, or maybe your feature needs to be split into smaller chunks that can be implemented independently.