Open Stack

Hello DefCore,

At this week’s Scale.11 meeting, we decided to move some existing artifacts out of the wiki and into Gerrit in order to ensure better control over changes [1].  I volunteered to migrate a few of the items and have begun working on doing so.  One item we didn’t decide on during the meeting was how to format these artifacts when migrating them into source control.  Since we’ve used RST for most of our other human-readable documents, I took the liberty of re-writing the first artifact in RST so we can see if that’s the format we want to go forward with for these.  I’ve submitted it as a patch this afternoon [2] for folks to have a look at.  I’m generally of the opinion that RST works fine for these documents, but would like to hear from others.  As noted in the commit message, there are a couple of trivial rendering changes involved, but the content is the same.  

I know that some folks also prefer to read RST documents in rendered form via our mirror on GitHub, so I’ve also posted the patch to my GitHub account [3] for those who’d like to see how GitHub renders it.  There’s one additional change that’s noticeable when viewing the GitHub rendering of the RST.  The original document has an enumerated list of principles, and each principle in the list has several sub-items.  In the original wiki, both the top-level and sub-level items are enumerated using digits (and I’ve retained that formatting).  However, GitHub’s rendering engine displays the sub-level items as lowercase roman numerals.  Otherwise, the rendering looks pretty close to what’s in the wiki.

Please have a look at the review [2] and let me know what you think…if we can reach consensus on the formatting quickly, I’ll push the remainder of the items on my plate shortly.

[1] https://etherpad.openstack.org/p/DefCoreScale.11
[2] https://review.openstack.org/172186
[3] https://github.com/markvoelker/defcore/blob/migrate_artifacts/coredefintion/CoreDefinition.rst

At Your Service,

Mark T. Voelker
OpenStack Architect