* [RFC PATCH] docs: add a diagram of the development process @ 2026-11-06 12:21 Alex Bennée 2026-11-06 17:38 ` Pierrick Bouvier 0 siblings, 1 reply; 5+ messages in thread From: Alex Bennée @ 2026-11-06 12:21 UTC (permalink / raw) To: qemu-devel Cc: Alex Bennée, Paolo Bonzini, John Snow, Peter Maydell, Mauro Carvalho Chehab, Pierrick Bouvier We've had various versions of this diagram for a while so I thought it would be worth adding to the developer docs. I chose plantuml as it has a plugin for sphinx that we can use and supports sequence diagrams which could be useful for documenting other features in the code base. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> --- vRFC - I've bundled all the plumbing together in this commit but it can be split up if we want to go forward. --- docs/conf.py | 22 +++++++++++++++ docs/devel/index-process.rst | 47 +++++++++++++++++++++++++++++++++ docs/meson.build | 3 ++- docs/requirements.txt | 1 + configure | 6 +++++ pythondeps.toml | 1 + tests/lcitool/mappings.yml | 3 +++ tests/lcitool/projects/qemu.yml | 1 + 8 files changed, 83 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 914bae67d9c..9fc7be362ba 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -66,8 +66,11 @@ 'qapi_domain', 'qapidoc', 'qmp_lexer', + 'sphinxcontrib.plantuml', ] +plantuml_output_format = 'svg' + # Add any paths that contain templates here, relative to this directory. templates_path = [os.path.join(qemu_docdir, '_templates')] @@ -345,3 +348,22 @@ qapidoc_srctree = os.path.join(qemu_docdir, '..') dbusdoc_srctree = os.path.join(qemu_docdir, '..') dbus_index_common_prefix = ["org.qemu."] + + +def setup(app): + import docutils.nodes + import sphinxcontrib.plantuml + + # We manually setup the plantuml extension so we can skip nodes with + # diagrams when generating the text based output. + + def skip_node(self, node): + raise docutils.nodes.SkipNode + + app.setup_extension('sphinxcontrib.plantuml') + app.add_node( + sphinxcontrib.plantuml.plantuml, + override=True, + man=(skip_node, None), + text=(skip_node, None), + ) diff --git a/docs/devel/index-process.rst b/docs/devel/index-process.rst index ce0f4e73197..1c13dd3f7b5 100644 --- a/docs/devel/index-process.rst +++ b/docs/devel/index-process.rst @@ -5,6 +5,53 @@ QEMU Community Processes Notes about how to interact with the community and how and where to submit patches. +.. uml:: + :caption: QEMU Patch Review and Acceptance Flow + + @startuml + skinparam roundCorner 8 + skinparam shadowing false + skinparam defaultFontName monospace + skinparam sequenceMessageAlign center + + actor "Developer" as dev + participant "QEMU Community\n(qemu-devel)" as list + actor "Subsystem\nMaintainer" as sub + actor "QEMU\nMaintainer" as top + + dev -> dev: Develop & test feature + + loop Needs revision (v1, v2, ... vn) + dev -> list: Post patch series to list + note over list: Code review on list + + opt Review comments + list -> dev: Feedback & change requests + dev -> dev: Incorporate feedback + end + opt Review tags + list -> dev: Tags (Reviewed-by, Acked-by, ...) + dev -> dev: Apply tags + end + + dev -> dev: Prepare n+1 + end + + group Patch acceptance & release + list -> sub: Maintainer accepts some or all patches + note over sub: Incorporates patches\nfrom other developers + sub -> sub: Add Maintainer Sign-off + sub -> sub: GIT branch foo/next + sub -> list: Sign & Submit Pull Request + list -> top: Pull Request delivered to list + note over top: Pull Requests from\nother maintainers + top -> top: Test and Merge Pull Reqs + top -> top: qemu.git master + top -> top: Tag Release + top -> list: QEMU Release + end + @enduml + .. toctree:: :maxdepth: 2 diff --git a/docs/meson.build b/docs/meson.build index 4d8cc545fcc..600d3283299 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -1,9 +1,10 @@ sphinx_build = find_program(fs.parent(python.full_path()) / 'sphinx-build', required: get_option('docs')) +plantuml = find_program('plantuml', required: get_option('docs')) # Check if tools are available to build documentation. build_docs = false -if sphinx_build.found() +if sphinx_build.found() and plantuml.found() SPHINX_ARGS = ['env', 'CONFDIR=' + qemu_confdir, sphinx_build, '-q'] # If we're making warnings fatal, apply this to Sphinx runs as well if get_option('werror') diff --git a/docs/requirements.txt b/docs/requirements.txt index 509d56bd1e8..1cafcbaa38f 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -3,3 +3,4 @@ sphinx==7.2.6 sphinx_rtd_theme==2.0.0 +sphinxcontrib-plantuml==0.30 diff --git a/configure b/configure index 42dffed28f0..b0dedde65dd 100755 --- a/configure +++ b/configure @@ -1020,6 +1020,12 @@ if test "$docs" != "disabled" ; then fi echo "Sphinx not found/usable, disabling docs." docs=disabled + elif ! has plantuml; then + if test "$docs" = "enabled" ; then + error_exit "plantuml not found" + fi + echo "plantuml not found, disabling docs." + docs=disabled else docs=enabled fi diff --git a/pythondeps.toml b/pythondeps.toml index c9a697046c6..c21d127ec93 100644 --- a/pythondeps.toml +++ b/pythondeps.toml @@ -30,6 +30,7 @@ meson = { accepted = ">=1.12.0", installed = "1.12.0", canary = "meson" } # Please keep the installed versions in sync with docs/requirements.txt sphinx = { accepted = ">=7.2.6", installed = "7.2.6", canary = "sphinx-build" } sphinx_rtd_theme = { accepted = ">=1.2.2", installed = "2.0.0" } +sphinxcontrib-plantuml = { accepted = ">=0.5", installed = "0.30" } # This test group is for dependencies required to run various tooling # and tests that should always be installed at configure time. It should diff --git a/tests/lcitool/mappings.yml b/tests/lcitool/mappings.yml index c99f007798e..eca6748ac09 100644 --- a/tests/lcitool/mappings.yml +++ b/tests/lcitool/mappings.yml @@ -3,6 +3,9 @@ mappings: bindgen: Ubuntu2204: + plantuml: + default: plantuml + python3: CentOSStream9: python3.12 diff --git a/tests/lcitool/projects/qemu.yml b/tests/lcitool/projects/qemu.yml index abbd3e3f0b8..de4395cd3c7 100644 --- a/tests/lcitool/projects/qemu.yml +++ b/tests/lcitool/projects/qemu.yml @@ -89,6 +89,7 @@ packages: - pcre-static - pixman - pkg-config + - plantuml - pulseaudio - python3 - python3-numpy -- 2.47.3 ^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [RFC PATCH] docs: add a diagram of the development process 2026-11-06 12:21 [RFC PATCH] docs: add a diagram of the development process Alex Bennée @ 2026-11-06 17:38 ` Pierrick Bouvier 2026-11-06 20:36 ` Alex Bennée 0 siblings, 1 reply; 5+ messages in thread From: Pierrick Bouvier @ 2026-11-06 17:38 UTC (permalink / raw) To: Alex Bennée, qemu-devel Cc: Paolo Bonzini, John Snow, Peter Maydell, Mauro Carvalho Chehab On 11/6/2026 4:21 AM, Alex Bennée wrote: > We've had various versions of this diagram for a while so I thought it > would be worth adding to the developer docs. I chose plantuml as it > has a plugin for sphinx that we can use and supports sequence diagrams > which could be useful for documenting other features in the code base. > > Signed-off-by: Alex Bennée <alex.bennee@linaro.org> > > --- > vRFC > - I've bundled all the plumbing together in this commit but it can > be split up if we want to go forward. > --- > docs/conf.py | 22 +++++++++++++++ > docs/devel/index-process.rst | 47 +++++++++++++++++++++++++++++++++ > docs/meson.build | 3 ++- > docs/requirements.txt | 1 + > configure | 6 +++++ > pythondeps.toml | 1 + > tests/lcitool/mappings.yml | 3 +++ > tests/lcitool/projects/qemu.yml | 1 + > 8 files changed, 83 insertions(+), 1 deletion(-) > > diff --git a/docs/conf.py b/docs/conf.py > index 914bae67d9c..9fc7be362ba 100644 > --- a/docs/conf.py > +++ b/docs/conf.py > @@ -66,8 +66,11 @@ > 'qapi_domain', > 'qapidoc', > 'qmp_lexer', > + 'sphinxcontrib.plantuml', > ] > > +plantuml_output_format = 'svg' > + > # Add any paths that contain templates here, relative to this directory. > templates_path = [os.path.join(qemu_docdir, '_templates')] > > @@ -345,3 +348,22 @@ > qapidoc_srctree = os.path.join(qemu_docdir, '..') > dbusdoc_srctree = os.path.join(qemu_docdir, '..') > dbus_index_common_prefix = ["org.qemu."] > + > + > +def setup(app): > + import docutils.nodes > + import sphinxcontrib.plantuml > + > + # We manually setup the plantuml extension so we can skip nodes with > + # diagrams when generating the text based output. > + > + def skip_node(self, node): > + raise docutils.nodes.SkipNode > + > + app.setup_extension('sphinxcontrib.plantuml') > + app.add_node( > + sphinxcontrib.plantuml.plantuml, > + override=True, > + man=(skip_node, None), > + text=(skip_node, None), > + ) > diff --git a/docs/devel/index-process.rst b/docs/devel/index-process.rst > index ce0f4e73197..1c13dd3f7b5 100644 > --- a/docs/devel/index-process.rst > +++ b/docs/devel/index-process.rst > @@ -5,6 +5,53 @@ QEMU Community Processes > > Notes about how to interact with the community and how and where to submit patches. > > +.. uml:: > + :caption: QEMU Patch Review and Acceptance Flow > + > + @startuml > + skinparam roundCorner 8 > + skinparam shadowing false > + skinparam defaultFontName monospace > + skinparam sequenceMessageAlign center > + > + actor "Developer" as dev > + participant "QEMU Community\n(qemu-devel)" as list > + actor "Subsystem\nMaintainer" as sub > + actor "QEMU\nMaintainer" as top > + > + dev -> dev: Develop & test feature > + > + loop Needs revision (v1, v2, ... vn) > + dev -> list: Post patch series to list > + note over list: Code review on list > + > + opt Review comments > + list -> dev: Feedback & change requests > + dev -> dev: Incorporate feedback > + end > + opt Review tags > + list -> dev: Tags (Reviewed-by, Acked-by, ...) > + dev -> dev: Apply tags > + end > + > + dev -> dev: Prepare n+1 > + end > + > + group Patch acceptance & release > + list -> sub: Maintainer accepts some or all patches > + note over sub: Incorporates patches\nfrom other developers > + sub -> sub: Add Maintainer Sign-off > + sub -> sub: GIT branch foo/next > + sub -> list: Sign & Submit Pull Request > + list -> top: Pull Request delivered to list > + note over top: Pull Requests from\nother maintainers > + top -> top: Test and Merge Pull Reqs > + top -> top: qemu.git master > + top -> top: Tag Release > + top -> list: QEMU Release > + end > + @enduml > + > .. toctree:: > :maxdepth: 2 > > diff --git a/docs/meson.build b/docs/meson.build > index 4d8cc545fcc..600d3283299 100644 > --- a/docs/meson.build > +++ b/docs/meson.build > @@ -1,9 +1,10 @@ > sphinx_build = find_program(fs.parent(python.full_path()) / 'sphinx-build', > required: get_option('docs')) > +plantuml = find_program('plantuml', required: get_option('docs')) > > # Check if tools are available to build documentation. > build_docs = false > -if sphinx_build.found() > +if sphinx_build.found() and plantuml.found() > SPHINX_ARGS = ['env', 'CONFDIR=' + qemu_confdir, sphinx_build, '-q'] > # If we're making warnings fatal, apply this to Sphinx runs as well > if get_option('werror') > diff --git a/docs/requirements.txt b/docs/requirements.txt > index 509d56bd1e8..1cafcbaa38f 100644 > --- a/docs/requirements.txt > +++ b/docs/requirements.txt > @@ -3,3 +3,4 @@ > > sphinx==7.2.6 > sphinx_rtd_theme==2.0.0 > +sphinxcontrib-plantuml==0.30 > diff --git a/configure b/configure > index 42dffed28f0..b0dedde65dd 100755 > --- a/configure > +++ b/configure > @@ -1020,6 +1020,12 @@ if test "$docs" != "disabled" ; then > fi > echo "Sphinx not found/usable, disabling docs." > docs=disabled > + elif ! has plantuml; then > + if test "$docs" = "enabled" ; then > + error_exit "plantuml not found" > + fi > + echo "plantuml not found, disabling docs." > + docs=disabled > else > docs=enabled > fi > diff --git a/pythondeps.toml b/pythondeps.toml > index c9a697046c6..c21d127ec93 100644 > --- a/pythondeps.toml > +++ b/pythondeps.toml > @@ -30,6 +30,7 @@ meson = { accepted = ">=1.12.0", installed = "1.12.0", canary = "meson" } > # Please keep the installed versions in sync with docs/requirements.txt > sphinx = { accepted = ">=7.2.6", installed = "7.2.6", canary = "sphinx-build" } > sphinx_rtd_theme = { accepted = ">=1.2.2", installed = "2.0.0" } > +sphinxcontrib-plantuml = { accepted = ">=0.5", installed = "0.30" } > > # This test group is for dependencies required to run various tooling > # and tests that should always be installed at configure time. It should > diff --git a/tests/lcitool/mappings.yml b/tests/lcitool/mappings.yml > index c99f007798e..eca6748ac09 100644 > --- a/tests/lcitool/mappings.yml > +++ b/tests/lcitool/mappings.yml > @@ -3,6 +3,9 @@ mappings: > bindgen: > Ubuntu2204: > > + plantuml: > + default: plantuml > + > python3: > CentOSStream9: python3.12 > > diff --git a/tests/lcitool/projects/qemu.yml b/tests/lcitool/projects/qemu.yml > index abbd3e3f0b8..de4395cd3c7 100644 > --- a/tests/lcitool/projects/qemu.yml > +++ b/tests/lcitool/projects/qemu.yml > @@ -89,6 +89,7 @@ packages: > - pcre-static > - pixman > - pkg-config > + - plantuml > - pulseaudio > - python3 > - python3-numpy It will silently disable doc by default for most of the people unfortunately, not sure it's the best move we can do. Maybe a simpler solution could be to generate diagrams out of sphinx, add them as a dependency, and generate a blank image (or an image with diagram source and a message - please install plantuml) if not available. What does plantuml brings compares to graphviz builtin extension? Also, text diagrams (https://asciidraw.github.io/) with raw formatting have the advantage to not require any external tool. What do you think? Regards, Pierrick ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [RFC PATCH] docs: add a diagram of the development process 2026-11-06 17:38 ` Pierrick Bouvier @ 2026-11-06 20:36 ` Alex Bennée 2026-11-06 21:01 ` Pierrick Bouvier 0 siblings, 1 reply; 5+ messages in thread From: Alex Bennée @ 2026-11-06 20:36 UTC (permalink / raw) To: Pierrick Bouvier Cc: qemu-devel, Paolo Bonzini, John Snow, Peter Maydell, Mauro Carvalho Chehab Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com> writes: > On 11/6/2026 4:21 AM, Alex Bennée wrote: >> We've had various versions of this diagram for a while so I thought it >> would be worth adding to the developer docs. I chose plantuml as it >> has a plugin for sphinx that we can use and supports sequence diagrams >> which could be useful for documenting other features in the code base. >> >> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> >> >> --- >> vRFC >> - I've bundled all the plumbing together in this commit but it can >> be split up if we want to go forward. >> --- >> docs/conf.py | 22 +++++++++++++++ >> docs/devel/index-process.rst | 47 +++++++++++++++++++++++++++++++++ >> docs/meson.build | 3 ++- >> docs/requirements.txt | 1 + >> configure | 6 +++++ >> pythondeps.toml | 1 + >> tests/lcitool/mappings.yml | 3 +++ >> tests/lcitool/projects/qemu.yml | 1 + >> 8 files changed, 83 insertions(+), 1 deletion(-) >> >> diff --git a/docs/conf.py b/docs/conf.py >> index 914bae67d9c..9fc7be362ba 100644 >> --- a/docs/conf.py >> +++ b/docs/conf.py >> @@ -66,8 +66,11 @@ >> 'qapi_domain', >> 'qapidoc', >> 'qmp_lexer', >> + 'sphinxcontrib.plantuml', >> ] >> >> +plantuml_output_format = 'svg' >> + >> # Add any paths that contain templates here, relative to this directory. >> templates_path = [os.path.join(qemu_docdir, '_templates')] >> >> @@ -345,3 +348,22 @@ >> qapidoc_srctree = os.path.join(qemu_docdir, '..') >> dbusdoc_srctree = os.path.join(qemu_docdir, '..') >> dbus_index_common_prefix = ["org.qemu."] >> + >> + >> +def setup(app): >> + import docutils.nodes >> + import sphinxcontrib.plantuml >> + >> + # We manually setup the plantuml extension so we can skip nodes with >> + # diagrams when generating the text based output. >> + >> + def skip_node(self, node): >> + raise docutils.nodes.SkipNode >> + >> + app.setup_extension('sphinxcontrib.plantuml') >> + app.add_node( >> + sphinxcontrib.plantuml.plantuml, >> + override=True, >> + man=(skip_node, None), >> + text=(skip_node, None), >> + ) >> diff --git a/docs/devel/index-process.rst b/docs/devel/index-process.rst >> index ce0f4e73197..1c13dd3f7b5 100644 >> --- a/docs/devel/index-process.rst >> +++ b/docs/devel/index-process.rst >> @@ -5,6 +5,53 @@ QEMU Community Processes >> >> Notes about how to interact with the community and how and where to submit patches. >> >> +.. uml:: >> + :caption: QEMU Patch Review and Acceptance Flow >> + >> + @startuml >> + skinparam roundCorner 8 >> + skinparam shadowing false >> + skinparam defaultFontName monospace >> + skinparam sequenceMessageAlign center >> + >> + actor "Developer" as dev >> + participant "QEMU Community\n(qemu-devel)" as list >> + actor "Subsystem\nMaintainer" as sub >> + actor "QEMU\nMaintainer" as top >> + >> + dev -> dev: Develop & test feature >> + >> + loop Needs revision (v1, v2, ... vn) >> + dev -> list: Post patch series to list >> + note over list: Code review on list >> + >> + opt Review comments >> + list -> dev: Feedback & change requests >> + dev -> dev: Incorporate feedback >> + end >> + opt Review tags >> + list -> dev: Tags (Reviewed-by, Acked-by, ...) >> + dev -> dev: Apply tags >> + end >> + >> + dev -> dev: Prepare n+1 >> + end >> + >> + group Patch acceptance & release >> + list -> sub: Maintainer accepts some or all patches >> + note over sub: Incorporates patches\nfrom other developers >> + sub -> sub: Add Maintainer Sign-off >> + sub -> sub: GIT branch foo/next >> + sub -> list: Sign & Submit Pull Request >> + list -> top: Pull Request delivered to list >> + note over top: Pull Requests from\nother maintainers >> + top -> top: Test and Merge Pull Reqs >> + top -> top: qemu.git master >> + top -> top: Tag Release >> + top -> list: QEMU Release >> + end >> + @enduml >> + >> .. toctree:: >> :maxdepth: 2 >> >> diff --git a/docs/meson.build b/docs/meson.build >> index 4d8cc545fcc..600d3283299 100644 >> --- a/docs/meson.build >> +++ b/docs/meson.build >> @@ -1,9 +1,10 @@ >> sphinx_build = find_program(fs.parent(python.full_path()) / 'sphinx-build', >> required: get_option('docs')) >> +plantuml = find_program('plantuml', required: get_option('docs')) >> >> # Check if tools are available to build documentation. >> build_docs = false >> -if sphinx_build.found() >> +if sphinx_build.found() and plantuml.found() >> SPHINX_ARGS = ['env', 'CONFDIR=' + qemu_confdir, sphinx_build, '-q'] >> # If we're making warnings fatal, apply this to Sphinx runs as well >> if get_option('werror') >> diff --git a/docs/requirements.txt b/docs/requirements.txt >> index 509d56bd1e8..1cafcbaa38f 100644 >> --- a/docs/requirements.txt >> +++ b/docs/requirements.txt >> @@ -3,3 +3,4 @@ >> >> sphinx==7.2.6 >> sphinx_rtd_theme==2.0.0 >> +sphinxcontrib-plantuml==0.30 >> diff --git a/configure b/configure >> index 42dffed28f0..b0dedde65dd 100755 >> --- a/configure >> +++ b/configure >> @@ -1020,6 +1020,12 @@ if test "$docs" != "disabled" ; then >> fi >> echo "Sphinx not found/usable, disabling docs." >> docs=disabled >> + elif ! has plantuml; then >> + if test "$docs" = "enabled" ; then >> + error_exit "plantuml not found" >> + fi >> + echo "plantuml not found, disabling docs." >> + docs=disabled >> else >> docs=enabled >> fi >> diff --git a/pythondeps.toml b/pythondeps.toml >> index c9a697046c6..c21d127ec93 100644 >> --- a/pythondeps.toml >> +++ b/pythondeps.toml >> @@ -30,6 +30,7 @@ meson = { accepted = ">=1.12.0", installed = "1.12.0", canary = "meson" } >> # Please keep the installed versions in sync with docs/requirements.txt >> sphinx = { accepted = ">=7.2.6", installed = "7.2.6", canary = "sphinx-build" } >> sphinx_rtd_theme = { accepted = ">=1.2.2", installed = "2.0.0" } >> +sphinxcontrib-plantuml = { accepted = ">=0.5", installed = "0.30" } >> >> # This test group is for dependencies required to run various tooling >> # and tests that should always be installed at configure time. It should >> diff --git a/tests/lcitool/mappings.yml b/tests/lcitool/mappings.yml >> index c99f007798e..eca6748ac09 100644 >> --- a/tests/lcitool/mappings.yml >> +++ b/tests/lcitool/mappings.yml >> @@ -3,6 +3,9 @@ mappings: >> bindgen: >> Ubuntu2204: >> >> + plantuml: >> + default: plantuml >> + >> python3: >> CentOSStream9: python3.12 >> >> diff --git a/tests/lcitool/projects/qemu.yml b/tests/lcitool/projects/qemu.yml >> index abbd3e3f0b8..de4395cd3c7 100644 >> --- a/tests/lcitool/projects/qemu.yml >> +++ b/tests/lcitool/projects/qemu.yml >> @@ -89,6 +89,7 @@ packages: >> - pcre-static >> - pixman >> - pkg-config >> + - plantuml >> - pulseaudio >> - python3 >> - python3-numpy > > It will silently disable doc by default for most of the people > unfortunately, not sure it's the best move we can do. plantuml seems to be pretty widely packaged so in this sense its just another dependency. > Maybe a simpler solution could be to generate diagrams out of sphinx, > add them as a dependency, and generate a blank image (or an image with > diagram source and a message - please install plantuml) if not > available. What does plantuml brings compares to graphviz builtin > extension? Ohh I didn't realize there was graphviz - I'll see if I can recreate with that. > Also, text diagrams (https://asciidraw.github.io/) with raw formatting > have the advantage to not require any external tool. I have the ascii original although ditaa seemed more of a stretch: --8<---------------cut here---------------start------------->8--- #+name: QEMU Development Process #+begin_src ditaa :cmdline -T -o :file images/qemu-dev-process.png Developer QEMU Community Subsystem Maintainer +-=--------------------------+ +-=---------------------------------------------------+ +-=----------------------+ | | | | | | | +-------------------+ | | +-----------------------------------------------+ | | +----------------+ | | |{io} | | | |{io} | | | |{io} | | | | Develop and | | +--->| Code Review on List | | +---->| Add Maintainer | | | | Test feature | | | | | | | | | | Sign-off | | | | | | | | +------+----------------+----------------+------+ | | | | | | | +--------+----------+ | | | | | | | | | +-------+--------+ | | | | | | V V V | | | | | | V | | : +-------------+ +-------------+ +-------------+ | | | v | | +-------------------+ | | | |{d} | |{d} | |{io} | | | | +----------------+ | | |{io} | | | | | Review | | Review | | Maintainer | | | | |{s} | | | +->| Post to List +-----+ | | Comments | | Tags | | accepts | | | | | GIT Branch | | | | | | | | | | | | | some or all | | | | | foo/next | | | | +-------------------+ | | | | | | | patches | | | | | | | | | : | +------+------+ +------+------+ +------+------+ | | : | | | | | +-------------------+ | | | | | | | | | | | | | |{io} |<----------------+ | +-----------+ | | | | | | | Incorporate | | | | | | | | | | Feedback |<---------------------------------+ | | | | | | | +--------+----------+ | | : | +-------+--------+ | | | | : +-----------------------------------------------------+ | | | | | v | | V | | | +-------------------+ | QEMU Maintainer | +----------------+ | | | |{io} | | +-=-----------------------------------------------------+ | |{io} | | | | | Prepare n+1 | | | +-------------+ +--------------+ +----------------+ | | | Sign & Submit | | | | | | | | |{io} | |{s} | |{io} | | | | Pull | | | | +--------+----------+ | | | Tag Release |<-+ qemu.git |<-+ Test and Merge |<-------+ Request | | | | | | | | | | master | | Pull Reqs |<-+ | | | | | +-----------+ | | | | | | | | || | +----------------+ | | | | +------+------+ +--------------+ +----------------+ || | | +----------------------------+ +--------+----------------------------------------------+| +------------------------+ +----------------+ | | | V | Pull Requests +--------------+ +---- from |{d} | Other Maintainers | QEMU | | Release | | | | | +--------------+ #+end_src --8<---------------cut here---------------end--------------->8--- > > What do you think? > > Regards, > Pierrick -- Alex Bennée Virtualisation Tech Lead @ Linaro ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [RFC PATCH] docs: add a diagram of the development process 2026-11-06 20:36 ` Alex Bennée @ 2026-11-06 21:01 ` Pierrick Bouvier 2026-11-09 11:01 ` Philippe Mathieu-Daudé 0 siblings, 1 reply; 5+ messages in thread From: Pierrick Bouvier @ 2026-11-06 21:01 UTC (permalink / raw) To: Alex Bennée Cc: qemu-devel, Paolo Bonzini, John Snow, Peter Maydell, Mauro Carvalho Chehab On 11/6/2026 12:36 PM, Alex Bennée wrote: > Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com> writes: > >> On 11/6/2026 4:21 AM, Alex Bennée wrote: >>> We've had various versions of this diagram for a while so I thought it >>> would be worth adding to the developer docs. I chose plantuml as it >>> has a plugin for sphinx that we can use and supports sequence diagrams >>> which could be useful for documenting other features in the code base. >>> >>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> >>> >>> --- >>> vRFC >>> - I've bundled all the plumbing together in this commit but it can >>> be split up if we want to go forward. >>> --- >>> docs/conf.py | 22 +++++++++++++++ >>> docs/devel/index-process.rst | 47 +++++++++++++++++++++++++++++++++ >>> docs/meson.build | 3 ++- >>> docs/requirements.txt | 1 + >>> configure | 6 +++++ >>> pythondeps.toml | 1 + >>> tests/lcitool/mappings.yml | 3 +++ >>> tests/lcitool/projects/qemu.yml | 1 + >>> 8 files changed, 83 insertions(+), 1 deletion(-) >>> >>> diff --git a/docs/conf.py b/docs/conf.py >>> index 914bae67d9c..9fc7be362ba 100644 >>> --- a/docs/conf.py >>> +++ b/docs/conf.py >>> @@ -66,8 +66,11 @@ >>> 'qapi_domain', >>> 'qapidoc', >>> 'qmp_lexer', >>> + 'sphinxcontrib.plantuml', >>> ] >>> >>> +plantuml_output_format = 'svg' >>> + >>> # Add any paths that contain templates here, relative to this directory. >>> templates_path = [os.path.join(qemu_docdir, '_templates')] >>> >>> @@ -345,3 +348,22 @@ >>> qapidoc_srctree = os.path.join(qemu_docdir, '..') >>> dbusdoc_srctree = os.path.join(qemu_docdir, '..') >>> dbus_index_common_prefix = ["org.qemu."] >>> + >>> + >>> +def setup(app): >>> + import docutils.nodes >>> + import sphinxcontrib.plantuml >>> + >>> + # We manually setup the plantuml extension so we can skip nodes with >>> + # diagrams when generating the text based output. >>> + >>> + def skip_node(self, node): >>> + raise docutils.nodes.SkipNode >>> + >>> + app.setup_extension('sphinxcontrib.plantuml') >>> + app.add_node( >>> + sphinxcontrib.plantuml.plantuml, >>> + override=True, >>> + man=(skip_node, None), >>> + text=(skip_node, None), >>> + ) >>> diff --git a/docs/devel/index-process.rst b/docs/devel/index-process.rst >>> index ce0f4e73197..1c13dd3f7b5 100644 >>> --- a/docs/devel/index-process.rst >>> +++ b/docs/devel/index-process.rst >>> @@ -5,6 +5,53 @@ QEMU Community Processes >>> >>> Notes about how to interact with the community and how and where to submit patches. >>> >>> +.. uml:: >>> + :caption: QEMU Patch Review and Acceptance Flow >>> + >>> + @startuml >>> + skinparam roundCorner 8 >>> + skinparam shadowing false >>> + skinparam defaultFontName monospace >>> + skinparam sequenceMessageAlign center >>> + >>> + actor "Developer" as dev >>> + participant "QEMU Community\n(qemu-devel)" as list >>> + actor "Subsystem\nMaintainer" as sub >>> + actor "QEMU\nMaintainer" as top >>> + >>> + dev -> dev: Develop & test feature >>> + >>> + loop Needs revision (v1, v2, ... vn) >>> + dev -> list: Post patch series to list >>> + note over list: Code review on list >>> + >>> + opt Review comments >>> + list -> dev: Feedback & change requests >>> + dev -> dev: Incorporate feedback >>> + end >>> + opt Review tags >>> + list -> dev: Tags (Reviewed-by, Acked-by, ...) >>> + dev -> dev: Apply tags >>> + end >>> + >>> + dev -> dev: Prepare n+1 >>> + end >>> + >>> + group Patch acceptance & release >>> + list -> sub: Maintainer accepts some or all patches >>> + note over sub: Incorporates patches\nfrom other developers >>> + sub -> sub: Add Maintainer Sign-off >>> + sub -> sub: GIT branch foo/next >>> + sub -> list: Sign & Submit Pull Request >>> + list -> top: Pull Request delivered to list >>> + note over top: Pull Requests from\nother maintainers >>> + top -> top: Test and Merge Pull Reqs >>> + top -> top: qemu.git master >>> + top -> top: Tag Release >>> + top -> list: QEMU Release >>> + end >>> + @enduml >>> + >>> .. toctree:: >>> :maxdepth: 2 >>> >>> diff --git a/docs/meson.build b/docs/meson.build >>> index 4d8cc545fcc..600d3283299 100644 >>> --- a/docs/meson.build >>> +++ b/docs/meson.build >>> @@ -1,9 +1,10 @@ >>> sphinx_build = find_program(fs.parent(python.full_path()) / 'sphinx-build', >>> required: get_option('docs')) >>> +plantuml = find_program('plantuml', required: get_option('docs')) >>> >>> # Check if tools are available to build documentation. >>> build_docs = false >>> -if sphinx_build.found() >>> +if sphinx_build.found() and plantuml.found() >>> SPHINX_ARGS = ['env', 'CONFDIR=' + qemu_confdir, sphinx_build, '-q'] >>> # If we're making warnings fatal, apply this to Sphinx runs as well >>> if get_option('werror') >>> diff --git a/docs/requirements.txt b/docs/requirements.txt >>> index 509d56bd1e8..1cafcbaa38f 100644 >>> --- a/docs/requirements.txt >>> +++ b/docs/requirements.txt >>> @@ -3,3 +3,4 @@ >>> >>> sphinx==7.2.6 >>> sphinx_rtd_theme==2.0.0 >>> +sphinxcontrib-plantuml==0.30 >>> diff --git a/configure b/configure >>> index 42dffed28f0..b0dedde65dd 100755 >>> --- a/configure >>> +++ b/configure >>> @@ -1020,6 +1020,12 @@ if test "$docs" != "disabled" ; then >>> fi >>> echo "Sphinx not found/usable, disabling docs." >>> docs=disabled >>> + elif ! has plantuml; then >>> + if test "$docs" = "enabled" ; then >>> + error_exit "plantuml not found" >>> + fi >>> + echo "plantuml not found, disabling docs." >>> + docs=disabled >>> else >>> docs=enabled >>> fi >>> diff --git a/pythondeps.toml b/pythondeps.toml >>> index c9a697046c6..c21d127ec93 100644 >>> --- a/pythondeps.toml >>> +++ b/pythondeps.toml >>> @@ -30,6 +30,7 @@ meson = { accepted = ">=1.12.0", installed = "1.12.0", canary = "meson" } >>> # Please keep the installed versions in sync with docs/requirements.txt >>> sphinx = { accepted = ">=7.2.6", installed = "7.2.6", canary = "sphinx-build" } >>> sphinx_rtd_theme = { accepted = ">=1.2.2", installed = "2.0.0" } >>> +sphinxcontrib-plantuml = { accepted = ">=0.5", installed = "0.30" } >>> >>> # This test group is for dependencies required to run various tooling >>> # and tests that should always be installed at configure time. It should >>> diff --git a/tests/lcitool/mappings.yml b/tests/lcitool/mappings.yml >>> index c99f007798e..eca6748ac09 100644 >>> --- a/tests/lcitool/mappings.yml >>> +++ b/tests/lcitool/mappings.yml >>> @@ -3,6 +3,9 @@ mappings: >>> bindgen: >>> Ubuntu2204: >>> >>> + plantuml: >>> + default: plantuml >>> + >>> python3: >>> CentOSStream9: python3.12 >>> >>> diff --git a/tests/lcitool/projects/qemu.yml b/tests/lcitool/projects/qemu.yml >>> index abbd3e3f0b8..de4395cd3c7 100644 >>> --- a/tests/lcitool/projects/qemu.yml >>> +++ b/tests/lcitool/projects/qemu.yml >>> @@ -89,6 +89,7 @@ packages: >>> - pcre-static >>> - pixman >>> - pkg-config >>> + - plantuml >>> - pulseaudio >>> - python3 >>> - python3-numpy >> >> It will silently disable doc by default for most of the people >> unfortunately, not sure it's the best move we can do. > > plantuml seems to be pretty widely packaged so in this sense its just > another dependency. > >> Maybe a simpler solution could be to generate diagrams out of sphinx, >> add them as a dependency, and generate a blank image (or an image with >> diagram source and a message - please install plantuml) if not >> available. What does plantuml brings compares to graphviz builtin >> extension? > > Ohh I didn't realize there was graphviz - I'll see if I can recreate > with that. > If graphviz is not installed, a warning is emitted, which stops the build since we turn warnings into error. The warning emitted has no type, so it can't be filtered with suppress_warning setting from sphinx-build. However, since sphinx uses standard logging framework, you can silence it this way: https://github.com/sphinx-doc/sphinx/issues/10219 ``` --- a/docs/conf.py +++ b/docs/conf.py @@ -24,6 +24,7 @@ +import logging import os import sys import sphinx @@ -66,8 +67,20 @@ 'qapi_domain', 'qapidoc', 'qmp_lexer', + 'sphinx.ext.graphviz', ] +# Render graphviz diagrams as SVG so they scale cleanly in HTML output. +graphviz_output_format = 'svg' + +# Silence the warning emitted by sphinx.ext.graphviz when 'dot' is not +# installed. Diagrams are then rendered as their raw source instead. +class _NoDotWarning(logging.Filter): + def filter(self, record): + return 'cannot be run (needed for graphviz output)' not in record.getMessage() + +logging.getLogger('sphinx.sphinx.ext.graphviz').addFilter(_NoDotWarning()) ``` The advantage is that graphviz is not a required dependency, so doc is still built for anyone having sphinx installed. That's a nice end result I think. >> Also, text diagrams (https://asciidraw.github.io/) with raw formatting >> have the advantage to not require any external tool. > > I have the ascii original although ditaa seemed more of a stretch: > > --8<---------------cut here---------------start------------->8--- > #+name: QEMU Development Process > #+begin_src ditaa :cmdline -T -o :file images/qemu-dev-process.png > Developer QEMU Community Subsystem Maintainer > +-=--------------------------+ +-=---------------------------------------------------+ +-=----------------------+ > | | | | | | > | +-------------------+ | | +-----------------------------------------------+ | | +----------------+ | > | |{io} | | | |{io} | | | |{io} | | > | | Develop and | | +--->| Code Review on List | | +---->| Add Maintainer | | > | | Test feature | | | | | | | | | | Sign-off | | > | | | | | | +------+----------------+----------------+------+ | | | | | | > | +--------+----------+ | | | | | | | | | +-------+--------+ | > | | | | | V V V | | | | | > | V | | : +-------------+ +-------------+ +-------------+ | | | v | > | +-------------------+ | | | |{d} | |{d} | |{io} | | | | +----------------+ | > | |{io} | | | | | Review | | Review | | Maintainer | | | | |{s} | | > | +->| Post to List +-----+ | | Comments | | Tags | | accepts | | | | | GIT Branch | | > | | | | | | | | | | | some or all | | | | | foo/next | | > | | +-------------------+ | | | | | | | patches | | | | | | | > | | : | +------+------+ +------+------+ +------+------+ | | : | | | > | | +-------------------+ | | | | | | | | | | | > | | |{io} |<----------------+ | +-----------+ | | | | > | | | Incorporate | | | | | | | > | | | Feedback |<---------------------------------+ | | | | | > | | +--------+----------+ | | : | +-------+--------+ | > | | | : +-----------------------------------------------------+ | | | > | | v | | V | > | | +-------------------+ | QEMU Maintainer | +----------------+ | > | | |{io} | | +-=-----------------------------------------------------+ | |{io} | | > | | | Prepare n+1 | | | +-------------+ +--------------+ +----------------+ | | | Sign & Submit | | > | | | | | | |{io} | |{s} | |{io} | | | | Pull | | > | | +--------+----------+ | | | Tag Release |<-+ qemu.git |<-+ Test and Merge |<-------+ Request | | > | | | | | | | | master | | Pull Reqs |<-+ | | | | > | +-----------+ | | | | | | | | || | +----------------+ | > | | | +------+------+ +--------------+ +----------------+ || | | > +----------------------------+ +--------+----------------------------------------------+| +------------------------+ > +----------------+ | > | | > V | Pull Requests > +--------------+ +---- from > |{d} | Other Maintainers > | QEMU | > | Release | > | | > | | > +--------------+ > > #+end_src > --8<---------------cut here---------------end--------------->8--- > Nice diagram! Better in picture indeed. > >> >> What do you think? >> >> Regards, >> Pierrick > ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [RFC PATCH] docs: add a diagram of the development process 2026-11-06 21:01 ` Pierrick Bouvier @ 2026-11-09 11:01 ` Philippe Mathieu-Daudé 0 siblings, 0 replies; 5+ messages in thread From: Philippe Mathieu-Daudé @ 2026-11-09 11:01 UTC (permalink / raw) To: Pierrick Bouvier, Alex Bennée Cc: qemu-devel, Paolo Bonzini, John Snow, Peter Maydell, Mauro Carvalho Chehab On 6/11/26 22:01, Pierrick Bouvier wrote: > On 11/6/2026 12:36 PM, Alex Bennée wrote: >> Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com> writes: >> >>> On 11/6/2026 4:21 AM, Alex Bennée wrote: >>>> We've had various versions of this diagram for a while so I thought it >>>> would be worth adding to the developer docs. I chose plantuml as it >>>> has a plugin for sphinx that we can use and supports sequence diagrams >>>> which could be useful for documenting other features in the code base. >>>> >>>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> >>>> >>>> --- >>>> vRFC >>>> - I've bundled all the plumbing together in this commit but it can >>>> be split up if we want to go forward. >>>> --- >>>> docs/conf.py | 22 +++++++++++++++ >>>> docs/devel/index-process.rst | 47 +++++++++++++++++++++++++++++++++ >>>> docs/meson.build | 3 ++- >>>> docs/requirements.txt | 1 + >>>> configure | 6 +++++ >>>> pythondeps.toml | 1 + >>>> tests/lcitool/mappings.yml | 3 +++ >>>> tests/lcitool/projects/qemu.yml | 1 + >>>> 8 files changed, 83 insertions(+), 1 deletion(-) >> I have the ascii original although ditaa seemed more of a stretch: >> >> --8<---------------cut here---------------start------------->8--- >> #+name: QEMU Development Process >> #+begin_src ditaa :cmdline -T -o :file images/qemu-dev-process.png >> Developer QEMU Community Subsystem Maintainer >> +-=--------------------------+ +-=---------------------------------------------------+ +-=----------------------+ >> | | | | | | >> | +-------------------+ | | +-----------------------------------------------+ | | +----------------+ | >> | |{io} | | | |{io} | | | |{io} | | >> | | Develop and | | +--->| Code Review on List | | +---->| Add Maintainer | | >> | | Test feature | | | | | | | | | | Sign-off | | >> | | | | | | +------+----------------+----------------+------+ | | | | | | >> | +--------+----------+ | | | | | | | | | +-------+--------+ | >> | | | | | V V V | | | | | >> | V | | : +-------------+ +-------------+ +-------------+ | | | v | >> | +-------------------+ | | | |{d} | |{d} | |{io} | | | | +----------------+ | >> | |{io} | | | | | Review | | Review | | Maintainer | | | | |{s} | | >> | +->| Post to List +-----+ | | Comments | | Tags | | accepts | | | | | GIT Branch | | >> | | | | | | | | | | | some or all | | | | | foo/next | | >> | | +-------------------+ | | | | | | | patches | | | | | | | >> | | : | +------+------+ +------+------+ +------+------+ | | : | | | >> | | +-------------------+ | | | | | | | | | | | >> | | |{io} |<----------------+ | +-----------+ | | | | >> | | | Incorporate | | | | | | | >> | | | Feedback |<---------------------------------+ | | | | | >> | | +--------+----------+ | | : | +-------+--------+ | >> | | | : +-----------------------------------------------------+ | | | >> | | v | | V | >> | | +-------------------+ | QEMU Maintainer | +----------------+ | >> | | |{io} | | +-=-----------------------------------------------------+ | |{io} | | >> | | | Prepare n+1 | | | +-------------+ +--------------+ +----------------+ | | | Sign & Submit | | >> | | | | | | |{io} | |{s} | |{io} | | | | Pull | | >> | | +--------+----------+ | | | Tag Release |<-+ qemu.git |<-+ Test and Merge |<-------+ Request | | >> | | | | | | | | master | | Pull Reqs |<-+ | | | | >> | +-----------+ | | | | | | | | || | +----------------+ | >> | | | +------+------+ +--------------+ +----------------+ || | | >> +----------------------------+ +--------+----------------------------------------------+| +------------------------+ >> +----------------+ | >> | | >> V | Pull Requests >> +--------------+ +---- from >> |{d} | Other Maintainers >> | QEMU | >> | Release | >> | | >> | | >> +--------------+ >> >> #+end_src >> --8<---------------cut here---------------end--------------->8--- >> > > Nice diagram! > Better in picture indeed. In the picture can we express the time dilatation factor in the arrows to help contributors understand when they shouldn't worry wrt QEMU mailing list pace? Like the wider the arrow the more we need to wait. ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2026-11-09 11:01 UTC | newest] Thread overview: 5+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2026-11-06 12:21 [RFC PATCH] docs: add a diagram of the development process Alex Bennée 2026-11-06 17:38 ` Pierrick Bouvier 2026-11-06 20:36 ` Alex Bennée 2026-11-06 21:01 ` Pierrick Bouvier 2026-11-09 11:01 ` Philippe Mathieu-Daudé
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.