Bug#914383: debian-policy: re-encode virtual package list in YAML

[Jonathan Dowland <jmtd@debian.org>]

Source: debian-policy
Severity: wishlist
Tags: patch

Implemented here:
<https://salsa.debian.org/jmtd/policy/commits/structured-vpackage-list>
<https://salsa.debian.org/jmtd/policy/commit/8948b734754f73022852c3839569e9416cb76ed1>

I repeat the commit log message here. It's worded in terms of absolutes, i.e.
"do this, do that", since that's what the commit does, however, please consider
this a proposal (which I am advocating for), i.e. "I propose converting...",
"I suggest deleting..." etc.

I've been thinking of this for a long time and another situation came up this
week where I thought it would be helpful so I sat down and did it.

----

Convert the plain-text virtual-package-names-list to a structured,
machine-readable document, encoded in YAML.

Delete the suffixed ChangeLog. From this point forward, changes to the file
should be recorded in the version control system in which Policy is maintained.

With the exception of the ChangeLog, preserve all the information in the text
version of the document, namely the virtual package name, the description, and
whether or not the virtual-package-provider normally provides an alternative.
The preamble and the section headings are preserved in the form of YAML
comments. The structured document should be just as legible for humans as the
prior version.

We expand the encoding of the alternative to include the binary path(s) that is
expected to be provided.

Rationale:

The current list cannot easily be machine-parsed. It's also likely out of date,
containing virtual package names that are not in use, and missing package names
that are in use. The pre-amble seems out-of-place and might better fit in the
policy document text.

By re-encoding in a machine-readable format, it shall be much easier to:

 • automate checking the status of the virtual package names herein against the
   names in use within the archive (e.g. from a UDD query).
 • check that a package which provides a virtual package name also registers
   paths in the alternatives system, if this document suggests it should (in
   e.g. lintian or some other QA tool)

I envisage many future possibilities, too, such as encoding more properties
about the "interface" of a program name registered as an alternative, such
as command-line arguments that should (or must) be accepted, etc.

The YAML schema is as follows (here in "Kwalify" syntax):

seq:
  - map:
      name: {type: str, required: True}
      description: {type: str, required: True}
      alternatives:
        seq:
         - {type: str, required: True}
        required: True

Future work:

 • simple tooling in the policy source tree to validate this file against
   the schema
 • house-keeping the list based on the names in use in-archive
 • lintian check for virtual package/alternatives correspondence
 • move the preamble out of this document and into a policy section
 • explore extensions to e.g. encode more properties about the nature of
   program names registered as alternatives


-- 
Jonathan Dowland