[libvirt] [PATCH v2] docs: attempt to document the general libvirt dev strategy

Mon Sep 30 16:26:07 UTC 2019

On Tue, 2019-09-24 at 16:33 +0100, Daniel P. Berrangé wrote:
> +<?xml version="1.0" encoding="UTF-8"?>

Throughout the document:

  s/meson/Meson/g
  s/M4/m4/g

> +<!DOCTYPE html>
> +<html xmlns="http://www.w3.org/1999/xhtml">
> +  <body>
> +    <h1>Libvirt Project Strategy</h1>

s/Libvirt// (it's redundant here).

> +
> +    <p>
> +      This document attempts to outline the libvirt project strategy for
> +      the near future. Think of this as a high level vision or todo list

s/todo/to-do/

> +    <h2>Language consolidation</h2>
> +
> +    <p>
> +      At time of writing libvirt uses the following languages

s/languages/languages:/

> +      <dt>Shell</dt>
> +      <dd>The autoconf configure script, is essentially shell script.

The use of "essentially" makes it sound like it's claiming to be
something else, which is not the case. I'd rewrite this as

  <code>configure</code>, generated by autoconf, is a shell script.

> +      <dt>M4</dt>
> +      <dd>The autoconf configure script uses a large number of M4 macros to

s/configure/<code>configure</code>/

> +    <p>
> +      The wide range of languages used present a knowledge burden for
> +      developers involved in libvirt, especially when there are multiple
> +      languages all used in the same problem spaces. This is most notable
> +      in the build system which uses a combination of shell, m4, make,
> +      automake, awk, sed, perl and python, with debugging requiring

s/perl and python/Perl and Python/

> +      understanding of the interactions between many languages. The
> +      relative popularity of the languages has implications for how easily
> +      the project can attract new contributors, and the quality of the code
> +      they'll be able to submit. This is most notable when comparing Perl
> +      to Python, as since the start of the libvirt project, the popularity
> +      and knowledge of Perl has declined, while Python has risen.

This last sentence just sounds weird to me. I would suggest something
like

  ... the popularity of Perl has declined, while Python has become
  more popular: this directly influences the amount and quality of
  contributions that can be expected for programs written in the
  respective languages.

> +      The C language has served libvirt well over the years, but its age shows
> +      giving rise to limitations which negatively impact the project in terms
> +      of code quality, reliability, and efficiency of development. Most notably
> +      its lack of memory safety means that many code bugs become trivially
> +      exploitable security flaws or denial of service. The lack of a high
> +      level portable runtime, resulting in a lot of effort being spent to

s/, resulting/results/

> +      ensure cross platform portability. The modern languages Rust and Go
> +      provide viable options for low level systems programming, in a way that
> +      was not practical with other common languages such as Python and Java.

s/was/is/

> +      With this in mind the libvirt project has set a vision for language
> +      usage in the future

s/future/future:/

> +      <dt>Python</dt>
> +      <dd>Various supporting build/test scripts are written in Python 3
> +        compatible mode only.</dd>

s/are written/are to be written/

> +      Some notable points from the above. Whether the core library / daemons
> +      will use Rust or Go internally is still to be decided based on more
> +      detailed evaluation to identify the best fit. The need to link and embed
> +      this functionality in other processes has complex interactions both at a
> +      technical and non-technical level. For standalone helper tools, either
> +      language is viable, but there are fewer concerns around interactions with
> +      other in-process code from 3rd parties. Thus a different decision may be
> +      made for daemons/libraries vs tools. Any rewrite proposed for existing
> +      functionality will have to weigh up the benefits of the new code,
> +      against the risk of introducing regressions wrt the previous code.

s/wrt/with respect to/

> +      The meson build system is written in Python 3. This directly informs the
> +      choice of Python 3 as the language for all supporting build scripts,
> +      re-inforcing the other benefits of Python, over Perl, Shell, M4,
> +      automake, etc. There is no intention to support Python 2 given meson's
> +      requirement for Python 3.

s/Python, over/Python over/

> +      Using the RST format for documentation allows for the use of XSLT to be
> +      eliminated from the build process. RST and the Sphinx toolkit are widely
> +      used, as seen by the huge repository of content on
> +      https://readthedocs.org/. The ability to embed raw HTML in the RST docs

As pointed out by Michal, this should be a clickable link.

With nits pointed out above fixed,

  Reviewed-by: Andrea Bolognani <abologna at redhat.com>

-- 
Andrea Bolognani / Red Hat / Virtualization