In our unconference sessions at OpenStack Docs Boot Camp, we talked about integration with development, the DocImpact flag, and I came up with these guidelines for what a DocImpact commit message should contain. I wanted to talk about it here on my blog before posting to the wiki to see if I’m missing anything crucial.
- Who would use the feature?
- Why use the feature?
- What is the exact usage for the feature? For a CLI call, provide examples of all the parameters the patch includes.
- Does the feature also have permissions/policies attached?
- If it is a configuration option, which flag grouping should it go into? (Defaults and a description are already required by their gate test on nova.)
I’ll walk through it with a DocImpact bug I worked on today titled “havana: nova Add force_nodes to scheduler hints“. I went on IRC to ask the developer the questions and got these answers:
- Who would use the feature? Only administrators using the baremetal driver for nova.
- Why use the feature? Baremetal is used when doing high-performance computing or standing up clouds from baremetal. Turns out, this driver is getting moved out of nova soon, and spans the realm of Heat + TripleO, and still a work in progress, but getting really close. HP is using it already to get compute nodes ready for action. This specific feature is used to specify exactly which node to send the next set of commands to.
- What is the exact usage for the feature? For a CLI call, provide examples of all the parameters the patch includes. It’s a call on the nova boot command with the –availability_zone flag, and you can have nova boot –availability_zone=zone:
host,node. You have to get the node in the form of a UUID. - Does the feature also have permissions/policies attached? In this case, it turns out some API features didn’t land in Havana, and so if you have to use a UUID for a baremetal node, then you have to do a SQL database call in order to get the UUID. This usage requiring database access is sort of “ugly” so I’m still trying to decide what to do with it. Also, I recall a lot of discussion around scheduler hints passed in with the –availability_zone flag so I’m still working on this doc bug. It would help greatly if the developer had done some of this end-user thinking up front, but he couldn’t have known back in May that the API changes wouldn’t land in September.
- If it is a configuration option, which flag grouping should it go into? (Defaults and a description are already required by their gate test on nova.) For the baremetal driver, we already have docs for the configuration reference, but it was a good check to do. I found that the wiki page had a redirect to a simpler page name, so I’ve included that in my patch.