Open Stack

On Tue, May 14, 2013 at 12:04 PM, Kashyap Chamarthy <kchamart at redhat.com>wrote:

> On 05/14/2013 09:37 PM, Daryl Walleck wrote:
> >>From my experience, doing a plain text test plan for applications with
> the complexity of Nova doesn't scale well. I tried that, but without ways
> to intelligently sort/search/group test cases, it became unmanageable when
> I actually needed to pull data from it. I've been tinkering with a test
> management tool based on Google's ACC methodology (
> http://code.google.com/p/test-analytics/wiki/AccExplained) that's solved
> some of my issues with managing test cases. It's definitely not perfect,
> but I'd be open to sharing what I've worked on and how I've broken out my
> test cases.
>
> Sure, interested to see your experience.
>
> When someone mentioned test-analytics, my quick attempt kept me waiting at
> "Loading project list".
>
> Meanwhile, I recently came across ASCII doc -- -- http://asciidoc.org/,
> and
> heard some very good reviews in community
>
> Reviews comparing it w/ various light weight markup languages:
>
> "I had the opportunity to seriously evaluate and contrast the serious
> lightweight markup languages: reStructuredText (and its complement Sphinx),
> Textile and AsciiDoc. Hands down, AsciiDoc is the winner. If there's such a
> thing as a sure thing in software, AsciiDoc is it."
>
>     - https://community.jboss.org/message/721016
>     - https://plus.google.com/114112334290393746697/posts/CdXJt6hVn5A
>
> Of-course, we don't *have* to take it on its face, but maybe doesn't hurt
> to
> evaluate?
>
> My 02 cents on why plain text ? (these are plain obvious, but just spelling
> out):
>
>
Plain text is great, and asciidoc is a clear winner from the OpenStack docs
perspective due to our existing build tools being able to handle it. It
converts to docbook easily. However, I'm not sure if this document you are
talking about needs to be published in any other format other than plain
text? If you just need a web page to point to, you might not need to go
through the trouble of publishing and could just use github's markdown and
point to the github page.
https://help.github.com/articles/github-flavored-markdown


>
> Pros:
>
>   (1) Text file are fast, easy to manage. I bet, they'll still be here 50
> years
>       later! These bulky "management systems" - I doubt that.
>
>   (2) Works well over bad internet connections/remotely (I often work w/ a
> 2GB
>       usb internet card). We can use tmux/screen session on a remote
> machine & work
>       peacefully.
>
>   (3) You can send patches, and apply them via the venerable git (and do
> all
>       other magic).
>
>   (4) Most (linux) developers are averse to clicky things. I've never seen
>       someone review. However, they're (some) happy to contribute tests if
> they're
>       text based approach somewhere in git files.
>
>   (5) OpenStack uses rST (for all its README & docs & everywhere else).
>       But, I'm aware, it's not the same as tests.
>
>   (6) Add your own..
>
>
> Cons:
>
>   (1) Integration with Jenkins, etc ?
>         - That's only needed for automation tests.
>
>
We can integrate and build API docs starting with asciidoc, markdown, or
rst. API docs so far are in docbook, WADL, or markdown. We have the High
Availability guide in asciidoc.


>   (2) Reporting (although we could write scripts, but it's difficult).
>
>   (3) Maintanability ?
>         - git ?
>
>   (4) I haven't seen any eamples of folks using text file based approach
> (that
>       doesn't mean it shouldn't be explored.
>

Take a look at the github.com/openstack/<project>-api repositories to see
how API docs are being maintained now.


>
>   (5) .. ?
>

(5) Tables are difficult to create and maintain in nearly all plain text
markups (if you need to add a column it's a pain, for example.)


>
>
> Don't hesitate to call me crazy, if I'm so. Thoughts ?
>
> PS: Just to explore rST, I recently wrote some quick instructions while
> testing
> nested virtualization w/ upstream kvm --
> https://raw.github.com/kashyapc/nvmx-haswell/master/SETUP-nVMX.rst (not
> the
> most beautifully formatted, but I don't hate it either):
>
> Thanks.
> --
> /kashyap
>
> _______________________________________________
> openstack-qa mailing list
> openstack-qa at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-qa
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-qa/attachments/20130517/dd1b3d4b/attachment-0001.html>