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/ __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
