Open Stack

On Tue, May 12 2015, Sean Dague wrote:

[]

> I mean try doing this workflow in ascii art -
> http://docs.openstack.org/infra/manual/developers.html and see if it's
> as clear.

Hello,

I am a newcomer, and for sure this diagram is not clear.  I guess this
is a bad chosen example.

For example there is the same string in more than one box
(eg. nova/master, nova/fix_bug_foo, Zuul/Jenkins...) and this is really
a source of confusion.

The boxes represent sometimes a tool, sometime a (state of a)
repository.

Also I think that the arrow with "git commit --amend" that starts from
gerrit is plain wrong.

Some arrows have a command associated, but what about those who do not,
how can I figure out how to trigger them?

Anyway is not difficult to rewrite it using plantuml[1] and everything
can be integrated with sphinx[2].

The code follows.  You can see the result by copy and paste in [1].

The fact that the result diagram is not clear to me is a symptom that
the underlying work-flow is not represented clearly.  If you like the
idea of using plantuml I can give a try to render it better as a real
state diagram.

@startuml

state "Upstream Code" as upstream {
  [*] --> unm
  state "nova/master" as unm
  state "Zuul/Jenkins\n(automated testing)" as j1
  state "Gerrit (Review System)\n\nReview Requirements:\n Core Reviews: 2 +2, 0 -2\nJenkins: +1" as g
  state "Zuul/Jenkins\n(automated testing)" as j2
}

state "Your Local Environment" as local {
  state "nova/master" as lnm
  state "nova/fix_bug_foo" as fix1
  state "nova/fix_bug_foo" as fix2
}

unm -> lnm : git clone
lnm -> fix1 : git branch fix_bug_foo
fix1 -> fix2 : Fix changes\nRun unit tests\ngit commit

fix2 -> g : git review

g -> fix2 : git commit --amend

g -> j2
j2 -> g

g -> j1
j1 -> unm

note left of j1 : gate queue
note left of j2 : check queue

@enduml
	
> We write things down to communicate, with people that aren't ourselves.
> Maybe there is a subset of humanity where ascii art is a clarifying
> wonder. I would argue it's a small subset, even in our community. So
> lets err on the side of communicating effectively in documentation with
> people that aren't just us.

+1 but this does not apply to the example.  Graphics should be used to
clarify things not to make shiny wrong diagrams.

Tools like plantuml or blokdiag[3] restrict the use of fancy graphics
and this should help people to focus on the meaningful part of the
picture.

I hope that this email communicate my points effectively. :-)

Best,
Daniele

[1] http://plantuml.sourceforge.net/index.html
[2] https://pypi.python.org/pypi/sphinxcontrib-plantuml
[3] http://blockdiag.com/en/