[PATCH v2 00/10] QoL tweaks and github action

[PATCH v2 00/10] QoL tweaks and github action

[Alex Bennée]

Some of these patches I've posted before. Along with general
quality of life tweaks to the build scripts we also introduce a github
workflow to build and publish the current working draft of the spec.

I also fixed a build regression with htlatex which became apparent
when I upgraded to Debian Trixie with a newer htlatex build.

v2

  - added README.md cleanup
  - applied r-b tags

The following still need review:

  .github: add a runner to build the latest draft
  make-setup-generated: optionally add GIT metadata
  virtio-html.cfg: implement workaround for htlatex regression
  specvars.tex: properly wrap arguments to \urldef
  README.md: convert embedded html to proper MarkDown
  LICENSE.md: convert html to proper MarkDown

Alex.

Alex Bennée (10):
  LICENSE.md: convert html to proper MarkDown
  README.md: convert embedded html to proper MarkDown
  REVISION: update to 1.4-wd01
  .gitpublish: update base to current working branch
  virtio-html.tex: sort package list
  specvars.tex: properly wrap arguments to \urldef
  virtio-html.cfg: implement workaround for htlatex regression
  make-setup-generated: optionally add GIT metadata
  Makefile: add some simple make automations
  .github: add a runner to build the latest draft

 .github/workflows/deploy.yaml |  37 ++++
 .github/workflows/test.yml    |  15 ++
 .gitpublish                   |   2 +-
 LICENSE.md                    |   8 +-
 Makefile                      |  33 +++
 README.md                     | 387 +++++++++++++---------------------
 REVISION                      |   2 +-
 make-setup-generated.sh       |  32 ++-
 makeall.sh                    |   4 +-
 makehtml.sh                   |   2 +-
 makepdf.sh                    |   2 +-
 specvars.tex                  |  14 +-
 virtio-html.cfg               |   3 +-
 virtio-html.tex               |  30 +--
 14 files changed, 298 insertions(+), 273 deletions(-)
 create mode 100644 .github/workflows/deploy.yaml
 create mode 100644 .github/workflows/test.yml
 create mode 100644 Makefile

-- 
2.47.3

[PATCH v2 01/10] LICENSE.md: convert html to proper MarkDown

[Alex Bennée]

There is no point embedding HTML inside the markdown document. It just
makes it messy to edit. The boilerplate text is maintained.

Cc: Robin Cover <robin@oasis-open.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-ID: <20251008145916.2626143-2-alex.bennee@linaro.org>
---
 LICENSE.md | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/LICENSE.md b/LICENSE.md
index ef558ec..8078023 100644
--- a/LICENSE.md
+++ b/LICENSE.md
@@ -1,7 +1,5 @@
-<div>
-<h2>License Terms</h2>
+## License Terms
 
-<p>Content in this GitHub code repository has been <a href="https://www.oasis-open.org/policies-guidelines/ipr#def-contribution">contributed</a> by OASIS TC Members, and is governed by the OASIS policies, including the <a href="https://www.oasis-open.org/policies-guidelines/ipr">Intellectual Property Rights (IPR) Policy</a>, the <a href="https://www.oasis-open.org/policies-guidelines/tc-process">Technical Committee (TC) Process</a>, <a href="https://www.oasis-open.org/policies-guidelines/bylaws">Bylaws</a>, and the Technical Committee's choice of <a href="https://www.oasis-open.org/policies-guidelines/ipr#def-ipr-mode">IPR Mode</a> (<i>viz</i>, <a href="https://www.oasis-open.org/policies-guidelines/ipr#Non-Assertion-Mode">Non-Assertion Mode</a>), including any applicable <a href="https://www.oasis-open.org/committees/virtio/ipr.php">declarations</a>. Feedback from non-TC members, if any, is governed by the terms of the <a href="https://www.oasis-open.org/policies-guidelines/ipr#appendixa">OASIS Feedback License</a>.</p>
+Content in this GitHub code repository has been [contributed](https://www.oasis-open.org/policies-guidelines/ipr#def-contribution) by OASIS TC Members, and is governed by the OASIS policies, including the [Intellectual Property Rights (IPR) Policy](https://www.oasis-open.org/policies-guidelines/ipr), the [Technical Committee (TC) Process](https://www.oasis-open.org/policies-guidelines/tc-process), [Bylaws](https://www.oasis-open.org/policies-guidelines/bylaws), and the Technical Committee's choice of [IPR Mode](https://www.oasis-open.org/policies-guidelines/ipr#def-ipr-mode) (_viz_, [Non-Assertion Mode](https://www.oasis-open.org/policies-guidelines/ipr#Non-Assertion-Mode)), including any applicable [declarations](https://www.oasis-open.org/committees/virtio/ipr.php). Feedback from non-TC members, if any, is governed by the terms of the [OASIS Feedback License](https://www.oasis-open.org/policies-guidelines/ipr#appendixa).
 
-<p>Description of this repository is presented in the <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/README.md">README</a> file, and guidelines for contribution/participation are given in the <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md">CONTRIBUTING</a> file.</p>
-</div>
+Description of this repository is presented in the [README](https://github.com/oasis-tcs/virtio-spec/blob/master/README.md) file, and guidelines for contribution/participation are given in the [CONTRIBUTING](https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md) file.
-- 
2.47.3

Re: [PATCH v2 01/10] LICENSE.md: convert html to proper MarkDown

[Manos Pitsidianakis]

On Fri, Oct 10, 2025 at 2:20 PM Alex Bennée <alex.bennee@linaro.org> wrote:
>
> There is no point embedding HTML inside the markdown document. It just
> makes it messy to edit. The boilerplate text is maintained.
>
> Cc: Robin Cover <robin@oasis-open.org>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Message-ID: <20251008145916.2626143-2-alex.bennee@linaro.org>
> ---
>  LICENSE.md | 8 +++-----
>  1 file changed, 3 insertions(+), 5 deletions(-)
>
> diff --git a/LICENSE.md b/LICENSE.md
> index ef558ec..8078023 100644
> --- a/LICENSE.md
> +++ b/LICENSE.md
> @@ -1,7 +1,5 @@
> -<div>
> -<h2>License Terms</h2>
> +## License Terms
>
> -<p>Content in this GitHub code repository has been <a href="https://www.oasis-open.org/policies-guidelines/ipr#def-contribution">contributed</a> by OASIS TC Members, and is governed by the OASIS policies, including the <a href="https://www.oasis-open.org/policies-guidelines/ipr">Intellectual Property Rights (IPR) Policy</a>, the <a href="https://www.oasis-open.org/policies-guidelines/tc-process">Technical Committee (TC) Process</a>, <a href="https://www.oasis-open.org/policies-guidelines/bylaws">Bylaws</a>, and the Technical Committee's choice of <a href="https://www.oasis-open.org/policies-guidelines/ipr#def-ipr-mode">IPR Mode</a> (<i>viz</i>, <a href="https://www.oasis-open.org/policies-guidelines/ipr#Non-Assertion-Mode">Non-Assertion Mode</a>), including any applicable <a href="https://www.oasis-open.org/committees/virtio/ipr.php">declarations</a>. Feedback from non-TC members, if any, is governed by the terms of the <a href="https://www.oasis-open.org/policies-guidelines/ipr#appendixa">OASIS Feedback License</a>.</p>
> +Content in this GitHub code repository has been [contributed](https://www.oasis-open.org/policies-guidelines/ipr#def-contribution) by OASIS TC Members, and is governed by the OASIS policies, including the [Intellectual Property Rights (IPR) Policy](https://www.oasis-open.org/policies-guidelines/ipr), the [Technical Committee (TC) Process](https://www.oasis-open.org/policies-guidelines/tc-process), [Bylaws](https://www.oasis-open.org/policies-guidelines/bylaws), and the Technical Committee's choice of [IPR Mode](https://www.oasis-open.org/policies-guidelines/ipr#def-ipr-mode) (_viz_, [Non-Assertion Mode](https://www.oasis-open.org/policies-guidelines/ipr#Non-Assertion-Mode)), including any applicable [declarations](https://www.oasis-open.org/committees/virtio/ipr.php). Feedback from non-TC members, if any, is governed by the terms of the [OASIS Feedback License](https://www.oasis-open.org/policies-guidelines/ipr#appendixa).
>
> -<p>Description of this repository is presented in the <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/README.md">README</a> file, and guidelines for contribution/participation are given in the <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md">CONTRIBUTING</a> file.</p>
> -</div>
> +Description of this repository is presented in the [README](https://github.com/oasis-tcs/virtio-spec/blob/master/README.md) file, and guidelines for contribution/participation are given in the [CONTRIBUTING](https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md) file.
> --
> 2.47.3
>
>

Reviewed-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org>

[PATCH v2 02/10] README.md: convert embedded html to proper MarkDown

[Alex Bennée]

There is no point embedding HTML inside the markdown document. It just
makes it messy to edit. The text is unchanged.

While I tried to exactly match the old layout I ended up making some
pragmatic fixes:

  - used # instead of ... in the code blocks
  - added missing - to "To do" sections
  - didn't attempt to block indent the lines notably "OSX users.." and
    the text under "Troubleshooting notes:"

The mailing list emails are also now properly linked for emphasis and
mailto: click-ability.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

---

GenAI usage: this is a fiddly file to edit by hand even with the full
power of Emacs. However the prompt:

  please rewrite this in github markdown, using ## and ### for
  headings, droping the extraneous <div> and <p> blocks and using
  proper markdown links. Leave the words themselves unchanged.

worked though it like a champ. As the change is mechanical I don't
think there are any copyright concerns so I'm happy to put my s-o-b on
the patch. I'm declaring the usage here because how LLMs can be used
in Open Source project is a live topic of debate.

After the mechanical changes I eyeballed the README on github and
manually tweaked the formatting to match the original layout as
closely as possible.
---
 README.md | 387 +++++++++++++++++++++---------------------------------
 1 file changed, 152 insertions(+), 235 deletions(-)

diff --git a/README.md b/README.md
index 13ab05b..c81a1c1 100644
--- a/README.md
+++ b/README.md
@@ -1,252 +1,169 @@
-<div>
-<h2>README</h2>
+## README
 
-<p>Members of the <a href="https://www.oasis-open.org/committees/virtio/">OASIS Virtual I/O Device (VIRTIO) TC</a> create and manage technical content in this TC GitHub repository ( <a href="https://github.com/oasis-tcs/virtio-spec">https://github.com/oasis-tcs/virtio-spec</a> ) as part of the TC's chartered work (<i>i.e.</i>, the program of work and deliverables described in its <a href="https://www.oasis-open.org/committees/virtio/charter.php">charter</a>).</p>
+Members of the [OASIS Virtual I/O Device (VIRTIO) TC](https://www.oasis-open.org/committees/virtio/) create and manage technical content in this TC GitHub repository ( [https://github.com/oasis-tcs/virtio-spec](https://github.com/oasis-tcs/virtio-spec) ) as part of the TC's chartered work (*i.e.*, the program of work and deliverables described in its [charter](https://www.oasis-open.org/committees/virtio/charter.php)).
 
-<p>OASIS TC GitHub repositories, as described in <a href="https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work">GitHub Repositories for OASIS TC Members' Chartered Work</a>, are governed by the OASIS <a href="https://www.oasis-open.org/policies-guidelines/tc-process">TC Process</a>, <a href="https://www.oasis-open.org/policies-guidelines/ipr">IPR Policy</a>, and other policies, similar to TC Wikis, TC JIRA issues tracking instances, TC SVN/Subversion repositories, etc.  While they make use of public GitHub repositories, these TC GitHub repositories are distinct from <a href="https://www.oasis-open.org/resources/open-repositories">OASIS Open Repositories</a>, which are used for development of open source <a href="https://www.oasis-open.org/resources/open-repositories/licenses">licensed</a> content.</p>
-</div>
+OASIS TC GitHub repositories, as described in [GitHub Repositories for OASIS TC Members' Chartered Work](https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work), are governed by the OASIS [TC Process](https://www.oasis-open.org/policies-guidelines/tc-process), [IPR Policy](https://www.oasis-open.org/policies-guidelines/ipr), and other policies, similar to TC Wikis, TC JIRA issues tracking instances, TC SVN/Subversion repositories, etc. While they make use of public GitHub repositories, these TC GitHub repositories are distinct from [OASIS Open Repositories](https://www.oasis-open.org/resources/open-repositories), which are used for development of open source [licensed](https://www.oasis-open.org/resources/open-repositories/licenses) content.
 
-<div>
-<h3>Description</h3>
+### Description
 
-<p>This repository includes the <a href="https://github.com/oasis-tcs/virtio-spec/releases">authoritative source</a> of the VIRTIO (Virtual I/O) Specification document. VIRTIO document describes the specifications of the "virtio" family of devices. These devices are found in virtual environments, yet by design they look like physical devices to the guest within the virtual machine &mdash; and this document treats them as such. This similarity allows the guest to use standard drivers and discovery mechanisms. </p>
+This repository includes the [authoritative source](https://github.com/oasis-tcs/virtio-spec/releases) of the VIRTIO (Virtual I/O) Specification document. VIRTIO document describes the specifications of the "virtio" family of devices. These devices are found in virtual environments, yet by design they look like physical devices to the guest within the virtual machine — and this document treats them as such. This similarity allows the guest to use standard drivers and discovery mechanisms.
 
-<p>The purpose of virtio and this specification is that virtual environments and guests should have a straightforward, efficient, standard and extensible mechanism for virtual devices, rather than boutique per-environment or per-OS mechanisms.</p>
-</div>
+The purpose of virtio and this specification is that virtual environments and guests should have a straightforward, efficient, standard and extensible mechanism for virtual devices, rather than boutique per-environment or per-OS mechanisms.
 
-<div>
-<h3>Contributions</h3>
-<p>As stated in this repository's <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md">CONTRIBUTING file</a>, contributors to this repository are expected to be Members of the OASIS virtio TC, for any substantive change requests.  Anyone wishing to contribute to this GitHub project and <a href="https://www.oasis-open.org/join/participation-instructions">participate</a> in the TC's technical activity is invited to join as an OASIS TC Member.  Public feedback is also accepted, subject to the terms of the <a href="https://www.oasis-open.org/policies-guidelines/ipr#appendixa">OASIS Feedback License</a>.</p>
-</div>
+### Contributions
 
+As stated in this repository's [CONTRIBUTING file](https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md), contributors to this repository are expected to be Members of the OASIS virtio TC, for any substantive change requests. Anyone wishing to contribute to this GitHub project and [participate](https://www.oasis-open.org/join/participation-instructions) in the TC's technical activity is invited to join as an OASIS TC Member. Public feedback is also accepted, subject to the terms of the [OASIS Feedback License](https://www.oasis-open.org/policies-guidelines/ipr#appendixa).
 
+### Licensing
 
-<div>
-<h3>Licensing</h3>
-<p>Please see the <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md">LICENSE</a> file for description of the license terms and OASIS policies applicable to the TC's work in this GitHub project. Content in this repository is intended to be part of the virtio TC's permanent record of activity, visible and freely available for all to use, subject to applicable OASIS policies, as presented in the repository <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md">LICENSE</a> file.</p>
-</div>
+Please see the [LICENSE](https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md) file for description of the license terms and OASIS policies applicable to the TC's work in this GitHub project. Content in this repository is intended to be part of the virtio TC's permanent record of activity, visible and freely available for all to use, subject to applicable OASIS policies, as presented in the repository [LICENSE](https://github.os-tcs/virtio-spec/blob/master/LICENSE.md) file.
 
-<div>
+### Further Description of this Repository
 
-<h3>Further Description of this Repository</h3>
-<h4>Building Instructions</h4>
-Authoritative version of the specification is maintained in the
-TeX document format. PDF and HTML versions are made available for
-ease of use and review.
-In order to build the HTML and PDF versions of the spec you will need the
-TeX document production system.
-The easiest way to get it up and running is probably by installing
-<a href="https://www.tug.org/texlive/">Tex-Live</a>.
+#### Building Instructions
 
-<dl>Installation cheat sheet:
-<dt>Fedora:</dt>
-<dd>
-<code>
+Authoritative version of the specification is maintained in the TeX document format. PDF and HTML versions are made available for ease of use and review. In order to build the HTML and PDF versions of the spec you will need the TeX document production system. The easiest way to get it up and running is probably by installing [Tex-Live](https://www.tug.org/texlive/).\
+Installation cheat sheet:
+
+***Fedora:***
+```bash
 sudo dnf install texlive-scheme-full
-</code></dd>
-<dt>
-Ubuntu and other Debian derivatives:
-</dt>
-<dd>
-<code>
+```
+***Ubuntu and other Debian derivatives:***
+```bash
 sudo apt-get install texlive-full
-</code></dd>
-<dt>OSX:<dt>
-<dd>OSX users don't need to install Tex-Live because they already have
-<a href="http://www.tug.org/mactex/">MacTeX</a> installed.
-</dd>
-</dl>
-<dl>The build process generates a ZIP package file including the
-original TeX sources, as well as HTML and PDF formatted
-versions of the specification.
-<dt>To generate the ZIP package, run:<dt>
-<dd>
-<code>
+```
+***OSX:***
+
+OSX users don't need to install Tex-Live because they already have [MacTeX](http://www.tug.org/mactex/) installed.
+
+The build process generates a ZIP package file including the original TeX sources, as well as HTML and PDF formatted versions of the specification.
+
+***To generate the ZIP package, run:***
+```bash
 ./makeall.sh
-</code>
-</dd>
-<dt>Troubleshooting notes:</dt>
-<dd> PDFs of the specification can be generated with
-either MicroSoft's Core fonts for the Web: Arial and Courier New,
-or Liberation fonts: Liberation Sans and Liberation Mono.
-Most systems come with one of these two variants included:
-should you get an error message about missing fonts,
-you will need to downloads and install one of the above
-font packages.
-<dd>
-</dl>
-<h4>Providing Feedback</h4>
-Informal feedback is accepted through the <strong>virtio-comment</strong> mailing list,
-and is archived in <A HREF="https://lore.kernel.org/virtio-comment/">the mailing list archives</A>.
-To provide feedback, subscribe by sending mail to
-<HREF="mailto:virtio-comment+subscribe@lists.linux.dev">virtio-comment+subscribe@lists.linux.dev</A>,
-then after confirming you agree to the IPR sending your feedback to
-<HREF="mailto:virtio-comment@lists.linux.dev">virtio-comment@lists.linux.dev</A>.
-<p>Note that only plain text part of the message is archived, and all
-attachments are stripped. Accordingly, messages sent to the
-mailing list should use text/plain encoding and not
-have any attachments.
-<p>The preferred form of providing feedback is in form of a patch.
-A patch can be generated and sent by cloning the spec repository,
-creating a commit, formatting it as a patch and then sending it.
-For example:
-<code>
-<p>
-git clone https://github.com/oasis-tcs/virtio-spec.git<br>
-... edit spec text, and save ...<br>
-<p>
-git commit -a<br>
-... describe the proposed change, in the following format:<br>
-single line summary<br>
-<br>
-detailed description, including motivation for the change<br>
-<br>
-Signed-off-by: Name &lt;email&gt;<br>
-... then save and close the editor ... <br>
-<p>
-git format-patch -o proposal1/ HEAD~1..<br>
-... generates a new directory proposal1/ and a file starting with 0001- ...<br>
-<p>
+```
+***Troubleshooting notes:***
+  
+PDFs of the specification can be generated with either MicroSoft's Core fonts for the Web: Arial and Courier New, or
+Liberation fonts: Liberation Sans and Liberation Mono. Most systems come with one of these two variants included: should
+you get an error message about missing fonts, you will need to downloads and install one of the above font packages.
+
+#### Providing Feedback
+
+Informal feedback is accepted through the **virtio-comment** mailing list, and is archived in [the mailing list archives](https://lore.kernel.org/virtio-comment/). To provide feedback, subscribe by sending mail to [virtio-comment+subscribe@lists.linux.dev](mailto:virtio-comment+subscribe@lists.linux.dev), then after confirming you agree to the IPR sending your feedback to [virtio-comment@lists.linux.dev](mailto:virtio-comment@lists.linux.dev). Note that only plain text part of the message is archived, and all attachments are stripped. Accordingly, messages sent to the mailing list should use `text/plain` encoding and not have any attachments.
+
+The preferred form of providing feedback is in form of a **patch**. A patch can be generated and sent by cloning the spec repository, creating a commit, formatting it as a patch and then sending it. For example:
+
+```bash
+git clone [https://github.com/oasis-tcs/virtio-spec.git](https://github.com/oasis-tcs/virtio-spec.git)
+# edit spec text, and save ...
+git commit -a
+```
+
+Describe the proposed change, in the following format:
+
+  > single line summary
+  > 
+  > detailed description, including motivation for the change
+  >
+  > Signed-off-by: Name <email>
+
+then save and close the editor
+
+```bash
+git format-patch -o proposal1/ HEAD~1..
+# generates a new directory proposal1/ and a file starting with 0001- ...
 git send-email --to=virtio-comment@lists.linux.dev proposal1/0001-*
-</code>
-
-<dl>Optionally, you can use <a
-href="https://github.com/stefanha/git-publish">git-publish</a> to submit a
-patch. This project already contains a <em>git-publish</em> profile that will
-configure some fields, e.g., <em>To</em> field with the right address. After you have
-installed <em>git-publish</em>, the procedure is the following:
-
-<code>
-<p>
-git checkout master -b my-feature<br>
-# work on new commits, add your 'Signed-off-by' lines to each<br>
-git publish<br>
-# more work, rebase on master, ...<br>
-git publish # will send a v2<br>
-</code>
-</dl>
-<dl>
-<dt>When to use the virtio-comment mailing list:</dt>
-<dd>
-  questions and change proposals for the Virtio specification,
-  including the specification of basic functionality, transports and
-  devices.
-</dd>
-
-<dt>When <em>not</em> to use the virtio-comment mailing list:</dt>
-<dd>
-  questions and change proposals for Virtio drivers and devices
-  implementing the specification.
-  (please use the <A HREF="mailto:virtio-dev@lists.linux.dev"> virtio-dev mailing list</A> for this).
-</dd>
-
-<dt>To do:</dt>
-<dd>
- send email preferably in text format (best for archiving).
-</dd>
-
-<dt>Not to do:</dt>
-<dd>
-<ul>
-<li> copy both virtio-dev and virtio-comment mailing lists (instead, pick one);
-<li> send full copies of the virtio spec (in any format).
-</ul>
-</dd>
-
-</dl>
-<h4>Note for TC Members</h4>
-<p>TC Members should review TC specific
-process rules under "Further Description of this Repository"
-in <A
-HREF="https://github.com/oasis-tcs/virtio-admin">https://github.com/oasis-tcs/virtio-admin</A>.
-
-</div>
-<h4>Implementation discussion</h4>
-Implementation discussion takes place on the <strong>virtio-dev</strong> mailing list,
-and is archived in <A HREF="https://lore.kernel.org/virtio-dev/">the mailing list archives</A>.
-To participate in the discussion, subscribe by sending mail to
-<HREF="mailto:virtio-dev+subscribe@lists.linux.dev">
-virtio-dev+subscribe@lists.linux.dev</A>.
-After agreeing to the IPR, to participate in the discussion, send
-mail to <HREF="mailto:virtio-dev@lists.linux.dev">virtio-dev@lists.linux.dev</A>.
-<p>This is the correct list to copy on Linux virtio UAPI change proposals.
-<p>Note that only the plain text part of the message is archived, and all
-attachments are stripped. Accordingly, messages sent to the
-mailing list should use text/plain encoding and not
-have any attachments.
-
-<dl>
-<dt>When to use the virtio-dev mailing list:</dt>
-<dd>
-  questions and change proposals for Virtio drivers and devices
-  implementing the specification.
-</dd>
-
-<dt>When <em>not</em> to use the virtio-dev mailing list:</dt>
-<dd>
-  questions and change proposals for the Virtio specification,
-  including the specification of basic functionality, transports and
-  devices (please use the <A HREF="mailto:virtio-comment@lists.linux.dev"> virtio-comment mailing list</A> for this).
-</dd>
-<dt>To do:</dt>
-<dd>
- send email preferably in text format (best for archiving).
-</dd>
-
-<dt>Not to do:</dt>
-<dd>
-copy both virtio-dev and virtio-comment mailing lists (instead, pick one).
-</dd>
-</dl>
-
-<h4>Use of github issues</h4>
-Note: according to the virtio TC rules, all official TC communication
-is taking place on one of the TC mailing lists.
-In particular, all comments must be provided on
-one of the TC mailing lists. Accordingly, the TC will not respond
-to comments provided in github issues: github issues are
-used solely to track integration of comments into the
-specification.<p>
+```
+
+Optionally, you can use [git-publish](https://github.com/stefanha/git-publish) to submit a patch. This project already contains a *git-publish* profile that will configure some fields, e.g., *To* field with the right address. After you have installed *git-publish*, the procedure is the following:
+
+```bash
+git checkout master -b my-feature
+# work on new commits, add your 'Signed-off-by' lines to each
+git publish
+# more work, rebase on master, ...
+git publish # will send a v2
+```
+
+***When to use the virtio-comment mailing list:***
+
+questions and change proposals for the Virtio specification, including the specification of basic functionality, transports and devices.
+
+***When not to use the virtio-comment mailing list:***
+
+questions and change proposals for Virtio drivers and devices implementing the specification. (please use the [virtio-dev mailing list](mailto:virtio-dev@lists.linux.dev) for this).
+
+***To do:***
+- send email preferably in text format (best for archiving).
+
+***Not to do:***
+- copy both virtio-dev and virtio-comment mailing lists (instead, pick one);
+- send full copies of the virtio spec (in any format).
+
+#### Note for TC Members
+
+TC Members should review TC specific process rules under "Further Description of this Repository" in [https://github.com/oasis-tcs/virtio-admin](https://github.com/oasis-tcs/virtio-admin)
+
+#### Implementation discussion
+
+Implementation discussion takes place on the **virtio-dev** mailing list, and is archived in [the mailing list archives](https://lore.kernel.org/virtio-dev/). To participate in the discussion, subscribe by sending mail to
+[virtio-dev+subscribe@lists.linux.dev](mailto:virtio-dev+subscribe@lists.linux.dev). After agreeing to the IPR, to participate in the discussion, send mail to [virtio-dev@lists.linux.dev](mailto:virtio-dev@lists.linux.dev). This is the correct list to copy on Linux virtio UAPI change proposals.
+
+Note that only the plain text part of the message is archived, and all attachments are stripped. Accordingly, messages sent to the mailing list should use text/plain encoding and not have any attachments.
+
+***When to use the virtio-dev mailing list:***
+
+questions and change proposals for Virtio drivers and devices implementing the specification.
+
+***When not to use the virtio-dev mailing list:***
+
+questions and change proposals for the Virtio specification, including the specification of basic functionality, transports and devices (please use the [virtio-comment mailing list](mailto:virtio-comment@lists.linux.dev) for this).
+
+***To do:***
+- send email preferably in text format (best for archiving).
+
+***Not to do:***
+- copy both virtio-dev and virtio-comment mailing lists (instead, pick one).
+
+#### Use of github issues
+
+Note: according to the virtio TC rules, all official TC communication is taking place on one of the TC mailing lists. In particular, all comments must be provided on one of the TC mailing lists. Accordingly, the TC will not respond to comments provided in github issues: github issues are used solely to track integration of comments into the specification.\
 To request a TC vote on resolving a specific comment:
-<ol>
-<li>Create a github issue, or edit an existing issue, with
-a short summary of the comment.
-The issue MUST specify
-the link to the latest proposal in the TC mailing list
-archives. <em>Note:</em> the link MUST be in the issue description itself -
-<em>not</em> in the comments.</li>
-<li>Reply by email to the comment email, requesting that the TC vote
-on resolving the issue.
-The mail requesting the vote should include the following, on a line by itself:<br>
-<code>
-Fixes: https://github.com/oasis-tcs/virtio-spec/issues/NNN
-</code>
-(NNN is the issue number)<br>
-For example, you can use the following template when requesting the TC vote:<br>
-<code>
-Could please open a voting ballot for these changes?<br>
-<br>
-Fixes: https://github.com/oasis-tcs/virtio-spec/issues/NNN<br>
-</code></li>
-<li>Please make sure to allow time for review between posting a comment
-and asking for a vote. </li>
-</ol>
-<h4>TC standing rules</h4>
-The TC adopted the following standing rule:
-<p>
-<em>
-Minor cleanups, including editorial formatting changes, spelling
-and typo fixes can be committed directly into git for approval as
-part of the next specification approval ballot.
-</em>
-<ol>
-<li>To request such a commit, reply by email to the comment email, requesting that the
-issue is resolved under the minor cleanups standing rule.
-</li>
-<li>Please make sure to allow time for review between posting a comment
-and asking for a commit. </li>
-</ol>
-
-<h3>Contact</h3>
-<p>Please send questions or comments about <a href="https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work">OASIS TC GitHub repositories</a> to <a href="mailto:robin@oasis-open.org">Robin Cover</a> and <a href="mailto:chet.ensign@oasis-open.org">Chet Ensign</a>.  For questions about content in this repository, please contact the TC Chair or Co-Chairs as listed on the the virtio TC's <a href="https://www.oasis-open.org/committees/virtio/">home page</a>.</p>
-</div>
+
+1. Create a github issue, or edit an existing issue, with a short summary of the comment.
+   The issue MUST specify the link to the latest proposal in the TC mailing list
+   archives. *Note:* the link MUST be in the issue description itself - *not* in the comments.
+
+2. Reply by email to the comment email, requesting that the TC vote on resolving the issue.
+   The mail requesting the vote should include the following, on a line by itself:
+
+   ```
+   Fixes: https://github.com/oasis-tcs/virtio-spec/issues/NNN
+   ```
+   (NNN is the issue number)
+
+   For example, you can use the following template when requesting the TC vote:
+
+   ```
+   Could please open a voting ballot for these changes?
+
+   Fixes: https://github.com/oasis-tcs/virtio-spec/issues/NNN
+   ```
+
+3. Please make sure to allow time for review between posting a comment and asking for a vote.
+
+#### TC standing rules
+
+The TC adopted the following standing rule:\
+*Minor cleanups, including editorial formatting changes, spelling and typo fixes can be committed directly into git for approval as part of the next specification approval ballot.*
+
+1. To request such a commit, reply by email to the comment email, requesting that the issue is resolved under the minor cleanups standing rule.
+2. Please make sure to allow time for review between posting a comment and asking for a commit.
+
+### Contact
+
+Please send questions or comments about [OASIS TC GitHub repositories](https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work)
+to [Robin Cover](mailto:robin@oasis-open.org) and [Chet Ensign](mailto:chet.ensign@oasis-open.org). For questions about content in this repository, please contact the TC Chair or Co-Chairs
+as listed on the the virtio TC's [home page](https://www.oasis-open.org/committees/virtio/).
-- 
2.47.3

[PATCH v2 03/10] REVISION: update to 1.4-wd01

[Alex Bennée]

The state of the repo is currently working on the 1.4 specification so
anything we generate should reflect that. It will be updated again on
the official release.

Reviewed-by: Parav Pandit <parav@nvidia.com>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-ID: <20251008145916.2626143-3-alex.bennee@linaro.org>
---
 REVISION | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/REVISION b/REVISION
index ba56baf..e3c043e 100644
--- a/REVISION
+++ b/REVISION
@@ -1 +1 @@
-virtio-v1.3-csd01
+virtio-v1.4-wd01
-- 
2.47.3

[PATCH v2 04/10] .gitpublish: update base to current working branch

[Alex Bennée]

The current working branch is virtio-1.4 so lets use that as our
reference for gitpublish.

Reviewed-by: Parav Pandit <parav@nvidia.com>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-ID: <20251008145916.2626143-4-alex.bennee@linaro.org>
---
 .gitpublish | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.gitpublish b/.gitpublish
index d412896..84414a7 100644
--- a/.gitpublish
+++ b/.gitpublish
@@ -1,3 +1,3 @@
 [gitpublishprofile "default"]
-base = master
+base = origin/virtio-1.4
 to = virtio-comment@lists.linux.dev
-- 
2.47.3

[PATCH v2 05/10] virtio-html.tex: sort package list

[Alex Bennée]

This will make auditing and adding new packages easier.

Reviewed-by: Parav Pandit <parav@nvidia.com>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-ID: <20251008145916.2626143-5-alex.bennee@linaro.org>
---
 virtio-html.tex | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/virtio-html.tex b/virtio-html.tex
index 48c633d..a43017a 100644
--- a/virtio-html.tex
+++ b/virtio-html.tex
@@ -5,34 +5,34 @@
 
 \documentclass[10pt,titlepage]{report}
 
-\usepackage{parskip}
-\usepackage{setspace}
+\usepackage[T1]{fontenc}
 \usepackage[english]{babel}
 \usepackage{ae,aecompl} 
-\usepackage[T1]{fontenc}
-\usepackage{graphicx}
+\usepackage{array}
+\usepackage{chngcntr}
+\usepackage{courier}
+\usepackage{enumitem}
+\usepackage{fancyhdr}
+\usepackage{fancyvrb}
 \usepackage{framed}
+\usepackage{graphicx}
 \usepackage{hyperref}
+\usepackage{lastpage}
 \usepackage{lineno} 
 \usepackage{listings}
-\usepackage{courier}
-\usepackage{fancyvrb}
-\usepackage{array}
 \usepackage{longtable}
+\usepackage{mdwlist}
 \usepackage{multirow}
+\usepackage{parskip}
 \usepackage{rotating}
-\usepackage{fancyhdr}
-\usepackage{lastpage}
-\usepackage{xcolor}
+\usepackage{setspace}
+\usepackage{tabularx}
 \usepackage{titlesec}
-\usepackage{mdwlist}
+\usepackage{underscore}
 \usepackage{url}
+\usepackage{xcolor}
 \usepackage{xifthen}
-\usepackage{tabularx}
-\usepackage{underscore}
 \usepackage{xstring}
-\usepackage{enumitem}
-\usepackage{chngcntr}
 \counterwithout{footnote}{chapter}
 
 \usepackage[utf8x]{inputenc}
-- 
2.47.3

[PATCH v2 06/10] specvars.tex: properly wrap arguments to \urldef

[Alex Bennée]

While the space in this case is probably harmless we should be using
non-ambiguous argument wrappers if don't want to drown linter output
with noise.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-ID: <20251008145916.2626143-6-alex.bennee@linaro.org>
---
 specvars.tex | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/specvars.tex b/specvars.tex
index a80557a..cf67070 100644
--- a/specvars.tex
+++ b/specvars.tex
@@ -3,13 +3,13 @@
 \newcommand{\virtiospecfile}{virtio-v\virtiorev-\virtiodraftstage\virtioworkingdraft}
 \newcommand{\virtiourlbase}{https://docs.oasis-open.org/virtio/virtio/v\virtiorev/\virtiodraftstage\virtioworkingdraft}
 %Below must be used to make links work correctly in HTML
-\urldef \virtiourllistings\url{\virtiourlbase/listings/}
-\urldef \virtiourltex\url{\virtiourlbase/tex/}
-\urldef \virtiourlpdf\url{\virtiourlbase/\virtiospecfile.pdf}
-\urldef \virtiourlhtml\url{\virtiourlbase/\virtiospecfile.html}
-\urldef \virtiourlh\url{\virtiourlbase/listings/virtio_queue.h}
-\urldef \virtiourllatestpdf\url{https://docs.oasis-open.org/virtio/virtio/v\virtiorev/virtio-v\virtiorev.pdf}
-\urldef \virtiourllatesthtml\url{https://docs.oasis-open.org/virtio/virtio/v\virtiorev/virtio-v\virtiorev.html}
+\urldef{\virtiourllistings}\url{\virtiourlbase/listings/}
+\urldef{\virtiourltex}\url{\virtiourlbase/tex/}
+\urldef{\virtiourlpdf}\url{\virtiourlbase/\virtiospecfile.pdf}
+\urldef{\virtiourlhtml}\url{\virtiourlbase/\virtiospecfile.html}
+\urldef{\virtiourlh}\url{\virtiourlbase/listings/virtio_queue.h}
+\urldef{\virtiourllatestpdf}\url{https://docs.oasis-open.org/virtio/virtio/v\virtiorev/virtio-v\virtiorev.pdf}
+\urldef{\virtiourllatesthtml}\url{https://docs.oasis-open.org/virtio/virtio/v\virtiorev/virtio-v\virtiorev.html}
 \newcommand{\virtioworkproduct}{Standards Track Work Product}
 \newcommand{\virtiooasiscopyright}{Copyright © OASIS Open 2023. All Rights Reserved.}
 
-- 
2.47.3

Re: [PATCH v2 06/10] specvars.tex: properly wrap arguments to \urldef

[Michael S. Tsirkin]

On Fri, Oct 10, 2025 at 12:20:06PM +0100, Alex Bennée wrote:
> While the space in this case is probably harmless we should be using
> non-ambiguous argument wrappers if don't want to drown linter output
> with noise.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Message-ID: <20251008145916.2626143-6-alex.bennee@linaro.org>


could you be more specfic which linter complains and how?

> ---
>  specvars.tex | 14 +++++++-------
>  1 file changed, 7 insertions(+), 7 deletions(-)
> 
> diff --git a/specvars.tex b/specvars.tex
> index a80557a..cf67070 100644
> --- a/specvars.tex
> +++ b/specvars.tex
> @@ -3,13 +3,13 @@
>  \newcommand{\virtiospecfile}{virtio-v\virtiorev-\virtiodraftstage\virtioworkingdraft}
>  \newcommand{\virtiourlbase}{https://docs.oasis-open.org/virtio/virtio/v\virtiorev/\virtiodraftstage\virtioworkingdraft}
>  %Below must be used to make links work correctly in HTML
> -\urldef \virtiourllistings\url{\virtiourlbase/listings/}
> -\urldef \virtiourltex\url{\virtiourlbase/tex/}
> -\urldef \virtiourlpdf\url{\virtiourlbase/\virtiospecfile.pdf}
> -\urldef \virtiourlhtml\url{\virtiourlbase/\virtiospecfile.html}
> -\urldef \virtiourlh\url{\virtiourlbase/listings/virtio_queue.h}
> -\urldef \virtiourllatestpdf\url{https://docs.oasis-open.org/virtio/virtio/v\virtiorev/virtio-v\virtiorev.pdf}
> -\urldef \virtiourllatesthtml\url{https://docs.oasis-open.org/virtio/virtio/v\virtiorev/virtio-v\virtiorev.html}
> +\urldef{\virtiourllistings}\url{\virtiourlbase/listings/}
> +\urldef{\virtiourltex}\url{\virtiourlbase/tex/}
> +\urldef{\virtiourlpdf}\url{\virtiourlbase/\virtiospecfile.pdf}
> +\urldef{\virtiourlhtml}\url{\virtiourlbase/\virtiospecfile.html}
> +\urldef{\virtiourlh}\url{\virtiourlbase/listings/virtio_queue.h}
> +\urldef{\virtiourllatestpdf}\url{https://docs.oasis-open.org/virtio/virtio/v\virtiorev/virtio-v\virtiorev.pdf}
> +\urldef{\virtiourllatesthtml}\url{https://docs.oasis-open.org/virtio/virtio/v\virtiorev/virtio-v\virtiorev.html}
>  \newcommand{\virtioworkproduct}{Standards Track Work Product}
>  \newcommand{\virtiooasiscopyright}{Copyright © OASIS Open 2023. All Rights Reserved.}
>  
> -- 
> 2.47.3
> 

Re: [PATCH v2 06/10] specvars.tex: properly wrap arguments to \urldef

[Alex Bennée]

"Michael S. Tsirkin" <mst@redhat.com> writes:

> On Fri, Oct 10, 2025 at 12:20:06PM +0100, Alex Bennée wrote:
>> While the space in this case is probably harmless we should be using
>> non-ambiguous argument wrappers if don't want to drown linter output
>> with noise.
>> 
>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>> Message-ID: <20251008145916.2626143-6-alex.bennee@linaro.org>
>
>
> could you be more specfic which linter complains and how?

will do - its not the only fix though. Latex is very noisy building so
I'm sure more consequential failures are being missed. It would be a big
job to tidy it up though.

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

[PATCH v2 07/10] virtio-html.cfg: implement workaround for htlatex regression

[Alex Bennée]

A regression in htlatex broke the building of html in new Debian
Trixie systems. The bug has been reported upstream:

  https://tug.org/pipermail/tex4ht/2025q4/003774.html

and the following change is a suggested workaround until the eventual
fix is reaches the texlive (and by implication distro) repos:

  https://svn.gnu.org.ua/viewvc/tex4ht/trunk/lit/tex4ht-html4.tex?r1=1750&r2=1749&pathrev=1750

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-ID: <20251008145916.2626143-7-alex.bennee@linaro.org>
---
 virtio-html.cfg | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/virtio-html.cfg b/virtio-html.cfg
index c5b9a94..63bf9af 100644
--- a/virtio-html.cfg
+++ b/virtio-html.cfg
@@ -1,4 +1,5 @@
-\Preamble{html} 
+\Preamble{html}
+\expandafter\providecommand\csname hline:color\endcsname{000}
 \begin{document}
 	\ConfigureMark{chapter}{\HCode{<hr><span class="titlemark">}\thechapter\HCode{</span>}}
 	\ConfigureMark{paragraph}{\HCode{<span class="titlemark">}\theparagraph\HCode{</span>}}
-- 
2.47.3

[PATCH v2 08/10] make-setup-generated: optionally add GIT metadata

[Alex Bennée]

This isn't a full conversion to git based metadata but it allows for
local builds to add git commit and tree status to the final built
product. The normal formal build process is unaffected and uses
manually updated VERSION, REVISION and REVISION-DATE metadata.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-ID: <20251008145916.2626143-8-alex.bennee@linaro.org>
---
 make-setup-generated.sh | 32 ++++++++++++++++++++++++++++----
 makeall.sh              |  4 ++--
 makehtml.sh             |  2 +-
 makepdf.sh              |  2 +-
 4 files changed, 32 insertions(+), 8 deletions(-)

diff --git a/make-setup-generated.sh b/make-setup-generated.sh
index 2c5c7f8..8d33ac5 100755
--- a/make-setup-generated.sh
+++ b/make-setup-generated.sh
@@ -1,16 +1,31 @@
 #! /bin/sh
+#
+# Generate version and metadata preamble for the document
+#
 
 DATESTR=${DATESTR:-`cat REVISION-DATE 2>/dev/null`}
-if [ x"$DATESTR" = x ]; then
-    ISODATE=`git show --format=format:'%cd' --date=iso | head -n 1`
-    DATESTR=`date -d "$DATE" +'%d %B %Y'`
+
+# If a second argument is passed we extract what we can from git
+# metadata (closest lightweight tag) and local tree status. This
+# allows locally generated copies to be tagged appropriately.
+#
+# The formal build process skips this.
+if ! test -z "$2"; then
+    TAG=$(git describe --dirty --tags)
+    # base date on now
+    DATESTR=$(date +'%d %B %Y')
+    COMMIT=$(git rev-parse --short HEAD)
+
+    # Finally check if we have un-committed changes in the tree
+    if ! git diff-index --quiet HEAD -- ; then
+        COMMIT="$COMMIT with local changes"
+    fi
 fi
 
 case "$1" in
     *-wd*)
 	STAGE=wd
 	STAGENAME="Working Draft"
-	WORKINGDRAFT=`basename "$1" | sed 's/.*-wd//'`
 	;;
     *-os*)
 	STAGE=os
@@ -41,6 +56,15 @@ esac
 
 VERSION=`echo "$1"| sed -e 's/virtio-v//' -e 's/-.*//'`
 
+#
+# Finally if we are building a local draft copy append the commit
+# details to the end of the working draft
+#
+if ! test -z "$COMMIT" ; then
+    STAGEEXTRATITLE="$STAGEEXTRATITLE (@ git $COMMIT)"
+fi
+
+
 #Prepend OASIS unless already there
 case "$STAGENAME" in
 	OASIS*)
diff --git a/makeall.sh b/makeall.sh
index 37e6c34..5f5d5dc 100755
--- a/makeall.sh
+++ b/makeall.sh
@@ -3,8 +3,8 @@
 export SPECDOC=${SPECDOC:-`cat REVISION`}
 export DATESTR=${DATESTR:-`cat REVISION-DATE`}
 ./makezip.sh
-./makehtml.sh
-./makepdf.sh
+./makehtml.sh $1
+./makepdf.sh $1
 zip $SPECDOC.zip $SPECDOC.pdf
 echo Generated file $SPECDOC.zip
 echo To change output file name, set SPECDOC environment variable
diff --git a/makehtml.sh b/makehtml.sh
index 45b7080..cf1a8d7 100755
--- a/makehtml.sh
+++ b/makehtml.sh
@@ -1,7 +1,7 @@
 #!/bin/sh
 
 SPECDOC=${SPECDOC:-`cat REVISION`}
-./make-setup-generated.sh "$SPECDOC"
+./make-setup-generated.sh "$SPECDOC" $1
 
 cp virtio-html.tex $SPECDOC.tex
 
diff --git a/makepdf.sh b/makepdf.sh
index 9cae903..bdfb8e5 100755
--- a/makepdf.sh
+++ b/makepdf.sh
@@ -1,7 +1,7 @@
 #!/bin/sh
 
 SPECDOC=${SPECDOC:-`cat REVISION`}
-./make-setup-generated.sh "$SPECDOC"
+./make-setup-generated.sh "$SPECDOC" $1
 
 rm $SPECDOC.aux $SPECDOC.pdf $SPECDOC.out
 xelatex --jobname $SPECDOC virtio.tex
-- 
2.47.3

Re: [PATCH v2 08/10] make-setup-generated: optionally add GIT metadata

[Michael S. Tsirkin]

On Fri, Oct 10, 2025 at 12:20:08PM +0100, Alex Bennée wrote:
> This isn't a full conversion to git based metadata but it allows for
> local builds to add git commit and tree status to the final built
> product. The normal formal build process is unaffected and uses
> manually updated VERSION, REVISION and REVISION-DATE metadata.

This violates oasis naming guidelines but I guess
as long as it is very clear this has no status beyond
a development help - okay I guess....

So what is the name format?


> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Message-ID: <20251008145916.2626143-8-alex.bennee@linaro.org>

Pls avoid Message-ID trailers in patches you post. It's really confusing.

> ---
>  make-setup-generated.sh | 32 ++++++++++++++++++++++++++++----
>  makeall.sh              |  4 ++--
>  makehtml.sh             |  2 +-
>  makepdf.sh              |  2 +-
>  4 files changed, 32 insertions(+), 8 deletions(-)
> 
> diff --git a/make-setup-generated.sh b/make-setup-generated.sh
> index 2c5c7f8..8d33ac5 100755
> --- a/make-setup-generated.sh
> +++ b/make-setup-generated.sh
> @@ -1,16 +1,31 @@
>  #! /bin/sh
> +#
> +# Generate version and metadata preamble for the document
> +#
>  
>  DATESTR=${DATESTR:-`cat REVISION-DATE 2>/dev/null`}
> -if [ x"$DATESTR" = x ]; then
> -    ISODATE=`git show --format=format:'%cd' --date=iso | head -n 1`
> -    DATESTR=`date -d "$DATE" +'%d %B %Y'`
> +
> +# If a second argument is passed we extract what we can from git
> +# metadata (closest lightweight tag) and local tree status. This
> +# allows locally generated copies to be tagged appropriately.
> +#
> +# The formal build process skips this.
> +if ! test -z "$2"; then
> +    TAG=$(git describe --dirty --tags)
> +    # base date on now
> +    DATESTR=$(date +'%d %B %Y')
> +    COMMIT=$(git rev-parse --short HEAD)
> +
> +    # Finally check if we have un-committed changes in the tree
> +    if ! git diff-index --quiet HEAD -- ; then
> +        COMMIT="$COMMIT with local changes"
> +    fi
>  fi
>  
>  case "$1" in
>      *-wd*)
>  	STAGE=wd
>  	STAGENAME="Working Draft"
> -	WORKINGDRAFT=`basename "$1" | sed 's/.*-wd//'`
>  	;;
>      *-os*)
>  	STAGE=os

This is used in the generated latex:
make-setup-generated.sh:\newcommand{\virtioworkingdraft}{$WORKINGDRAFT}

Are you sure output for a wd is unaffected?
We still need to be able to generate these for the TC process.


> @@ -41,6 +56,15 @@ esac
>  
>  VERSION=`echo "$1"| sed -e 's/virtio-v//' -e 's/-.*//'`
>  
> +#
> +# Finally if we are building a local draft copy append the commit
> +# details to the end of the working draft
> +#
> +if ! test -z "$COMMIT" ; then
> +    STAGEEXTRATITLE="$STAGEEXTRATITLE (@ git $COMMIT)"
> +fi
> +
> +
>  #Prepend OASIS unless already there
>  case "$STAGENAME" in
>  	OASIS*)
> diff --git a/makeall.sh b/makeall.sh
> index 37e6c34..5f5d5dc 100755
> --- a/makeall.sh
> +++ b/makeall.sh
> @@ -3,8 +3,8 @@
>  export SPECDOC=${SPECDOC:-`cat REVISION`}
>  export DATESTR=${DATESTR:-`cat REVISION-DATE`}
>  ./makezip.sh
> -./makehtml.sh
> -./makepdf.sh
> +./makehtml.sh $1
> +./makepdf.sh $1
>  zip $SPECDOC.zip $SPECDOC.pdf
>  echo Generated file $SPECDOC.zip
>  echo To change output file name, set SPECDOC environment variable
> diff --git a/makehtml.sh b/makehtml.sh
> index 45b7080..cf1a8d7 100755
> --- a/makehtml.sh
> +++ b/makehtml.sh
> @@ -1,7 +1,7 @@
>  #!/bin/sh
>  
>  SPECDOC=${SPECDOC:-`cat REVISION`}
> -./make-setup-generated.sh "$SPECDOC"
> +./make-setup-generated.sh "$SPECDOC" $1
>  
>  cp virtio-html.tex $SPECDOC.tex
>  
> diff --git a/makepdf.sh b/makepdf.sh
> index 9cae903..bdfb8e5 100755
> --- a/makepdf.sh
> +++ b/makepdf.sh
> @@ -1,7 +1,7 @@
>  #!/bin/sh
>  
>  SPECDOC=${SPECDOC:-`cat REVISION`}
> -./make-setup-generated.sh "$SPECDOC"
> +./make-setup-generated.sh "$SPECDOC" $1
>  
>  rm $SPECDOC.aux $SPECDOC.pdf $SPECDOC.out
>  xelatex --jobname $SPECDOC virtio.tex
> -- 
> 2.47.3
> 

Re: [PATCH v2 08/10] make-setup-generated: optionally add GIT metadata

[Alex Bennée]

"Michael S. Tsirkin" <mst@redhat.com> writes:

> On Fri, Oct 10, 2025 at 12:20:08PM +0100, Alex Bennée wrote:
<snip>
>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>> Message-ID: <20251008145916.2626143-8-alex.bennee@linaro.org>
>
> Pls avoid Message-ID trailers in patches you post. It's really
> confusing.

That was added by b4 - I can add a .b4-config to stop that happening
accidentally. I see the git history has Links instead, e.g.:

 Link: https://lore.kernel.org/r/20250305164546.1484029-1-mvaralar@redhat.com

is that OK?

>
>> ---
>>  make-setup-generated.sh | 32 ++++++++++++++++++++++++++++----
>>  makeall.sh              |  4 ++--
>>  makehtml.sh             |  2 +-
>>  makepdf.sh              |  2 +-
>>  4 files changed, 32 insertions(+), 8 deletions(-)
>> 
>> diff --git a/make-setup-generated.sh b/make-setup-generated.sh
>> index 2c5c7f8..8d33ac5 100755
>> --- a/make-setup-generated.sh
>> +++ b/make-setup-generated.sh
>> @@ -1,16 +1,31 @@
>>  #! /bin/sh
>> +#
>> +# Generate version and metadata preamble for the document
>> +#
>>  
>>  DATESTR=${DATESTR:-`cat REVISION-DATE 2>/dev/null`}
>> -if [ x"$DATESTR" = x ]; then
>> -    ISODATE=`git show --format=format:'%cd' --date=iso | head -n 1`
>> -    DATESTR=`date -d "$DATE" +'%d %B %Y'`
>> +
>> +# If a second argument is passed we extract what we can from git
>> +# metadata (closest lightweight tag) and local tree status. This
>> +# allows locally generated copies to be tagged appropriately.
>> +#
>> +# The formal build process skips this.
>> +if ! test -z "$2"; then
>> +    TAG=$(git describe --dirty --tags)
>> +    # base date on now
>> +    DATESTR=$(date +'%d %B %Y')
>> +    COMMIT=$(git rev-parse --short HEAD)
>> +
>> +    # Finally check if we have un-committed changes in the tree
>> +    if ! git diff-index --quiet HEAD -- ; then
>> +        COMMIT="$COMMIT with local changes"
>> +    fi
>>  fi
>>  
>>  case "$1" in
>>      *-wd*)
>>  	STAGE=wd
>>  	STAGENAME="Working Draft"
>> -	WORKINGDRAFT=`basename "$1" | sed 's/.*-wd//'`
>>  	;;
>>      *-os*)
>>  	STAGE=os
>
> This is used in the generated latex:
> make-setup-generated.sh:\newcommand{\virtioworkingdraft}{$WORKINGDRAFT}
>
> Are you sure output for a wd is unaffected?
> We still need to be able to generate these for the TC process.
>
>
>> @@ -41,6 +56,15 @@ esac
>>  
>>  VERSION=`echo "$1"| sed -e 's/virtio-v//' -e 's/-.*//'`
>>  
>> +#
>> +# Finally if we are building a local draft copy append the commit
>> +# details to the end of the working draft
>> +#
>> +if ! test -z "$COMMIT" ; then
>> +    STAGEEXTRATITLE="$STAGEEXTRATITLE (@ git $COMMIT)"
>> +fi
>> +
>> +
>>  #Prepend OASIS unless already there
>>  case "$STAGENAME" in
>>  	OASIS*)
>> diff --git a/makeall.sh b/makeall.sh
>> index 37e6c34..5f5d5dc 100755
>> --- a/makeall.sh
>> +++ b/makeall.sh
>> @@ -3,8 +3,8 @@
>>  export SPECDOC=${SPECDOC:-`cat REVISION`}
>>  export DATESTR=${DATESTR:-`cat REVISION-DATE`}
>>  ./makezip.sh
>> -./makehtml.sh
>> -./makepdf.sh
>> +./makehtml.sh $1
>> +./makepdf.sh $1
>>  zip $SPECDOC.zip $SPECDOC.pdf
>>  echo Generated file $SPECDOC.zip
>>  echo To change output file name, set SPECDOC environment variable
>> diff --git a/makehtml.sh b/makehtml.sh
>> index 45b7080..cf1a8d7 100755
>> --- a/makehtml.sh
>> +++ b/makehtml.sh
>> @@ -1,7 +1,7 @@
>>  #!/bin/sh
>>  
>>  SPECDOC=${SPECDOC:-`cat REVISION`}
>> -./make-setup-generated.sh "$SPECDOC"
>> +./make-setup-generated.sh "$SPECDOC" $1
>>  
>>  cp virtio-html.tex $SPECDOC.tex
>>  
>> diff --git a/makepdf.sh b/makepdf.sh
>> index 9cae903..bdfb8e5 100755
>> --- a/makepdf.sh
>> +++ b/makepdf.sh
>> @@ -1,7 +1,7 @@
>>  #!/bin/sh
>>  
>>  SPECDOC=${SPECDOC:-`cat REVISION`}
>> -./make-setup-generated.sh "$SPECDOC"
>> +./make-setup-generated.sh "$SPECDOC" $1
>>  
>>  rm $SPECDOC.aux $SPECDOC.pdf $SPECDOC.out
>>  xelatex --jobname $SPECDOC virtio.tex
>> -- 
>> 2.47.3
>> 

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

Re: [PATCH v2 08/10] make-setup-generated: optionally add GIT metadata

[Michael S. Tsirkin]

On Fri, Oct 10, 2025 at 02:10:25PM +0100, Alex Bennée wrote:
> "Michael S. Tsirkin" <mst@redhat.com> writes:
> 
> > On Fri, Oct 10, 2025 at 12:20:08PM +0100, Alex Bennée wrote:
> <snip>
> >> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> >> Message-ID: <20251008145916.2626143-8-alex.bennee@linaro.org>
> >
> > Pls avoid Message-ID trailers in patches you post. It's really
> > confusing.
> 
> That was added by b4 - I can add a .b4-config to stop that happening
> accidentally. I see the git history has Links instead, e.g.:
> 
>  Link: https://lore.kernel.org/r/20250305164546.1484029-1-mvaralar@redhat.com
> 
> is that OK?



No, please don't add links for no point. Add a link if you are
linking to some relevant discussion.


When maintainers apply patches they can have b4 add
message id in b4 am/shazam command. It's not the default though
and that is maintainer flow not contributor flow.


Parav started adding these links automatically with -l, I personally
prefer -i so that links have meaning. Not worth my time
fighting about though.


> >
> >> ---
> >>  make-setup-generated.sh | 32 ++++++++++++++++++++++++++++----
> >>  makeall.sh              |  4 ++--
> >>  makehtml.sh             |  2 +-
> >>  makepdf.sh              |  2 +-
> >>  4 files changed, 32 insertions(+), 8 deletions(-)
> >> 
> >> diff --git a/make-setup-generated.sh b/make-setup-generated.sh
> >> index 2c5c7f8..8d33ac5 100755
> >> --- a/make-setup-generated.sh
> >> +++ b/make-setup-generated.sh
> >> @@ -1,16 +1,31 @@
> >>  #! /bin/sh
> >> +#
> >> +# Generate version and metadata preamble for the document
> >> +#
> >>  
> >>  DATESTR=${DATESTR:-`cat REVISION-DATE 2>/dev/null`}
> >> -if [ x"$DATESTR" = x ]; then
> >> -    ISODATE=`git show --format=format:'%cd' --date=iso | head -n 1`
> >> -    DATESTR=`date -d "$DATE" +'%d %B %Y'`
> >> +
> >> +# If a second argument is passed we extract what we can from git
> >> +# metadata (closest lightweight tag) and local tree status. This
> >> +# allows locally generated copies to be tagged appropriately.
> >> +#
> >> +# The formal build process skips this.
> >> +if ! test -z "$2"; then
> >> +    TAG=$(git describe --dirty --tags)
> >> +    # base date on now
> >> +    DATESTR=$(date +'%d %B %Y')
> >> +    COMMIT=$(git rev-parse --short HEAD)
> >> +
> >> +    # Finally check if we have un-committed changes in the tree
> >> +    if ! git diff-index --quiet HEAD -- ; then
> >> +        COMMIT="$COMMIT with local changes"
> >> +    fi
> >>  fi
> >>  
> >>  case "$1" in
> >>      *-wd*)
> >>  	STAGE=wd
> >>  	STAGENAME="Working Draft"
> >> -	WORKINGDRAFT=`basename "$1" | sed 's/.*-wd//'`
> >>  	;;
> >>      *-os*)
> >>  	STAGE=os
> >
> > This is used in the generated latex:
> > make-setup-generated.sh:\newcommand{\virtioworkingdraft}{$WORKINGDRAFT}
> >
> > Are you sure output for a wd is unaffected?
> > We still need to be able to generate these for the TC process.
> >
> >
> >> @@ -41,6 +56,15 @@ esac
> >>  
> >>  VERSION=`echo "$1"| sed -e 's/virtio-v//' -e 's/-.*//'`
> >>  
> >> +#
> >> +# Finally if we are building a local draft copy append the commit
> >> +# details to the end of the working draft
> >> +#
> >> +if ! test -z "$COMMIT" ; then
> >> +    STAGEEXTRATITLE="$STAGEEXTRATITLE (@ git $COMMIT)"
> >> +fi
> >> +
> >> +
> >>  #Prepend OASIS unless already there
> >>  case "$STAGENAME" in
> >>  	OASIS*)
> >> diff --git a/makeall.sh b/makeall.sh
> >> index 37e6c34..5f5d5dc 100755
> >> --- a/makeall.sh
> >> +++ b/makeall.sh
> >> @@ -3,8 +3,8 @@
> >>  export SPECDOC=${SPECDOC:-`cat REVISION`}
> >>  export DATESTR=${DATESTR:-`cat REVISION-DATE`}
> >>  ./makezip.sh
> >> -./makehtml.sh
> >> -./makepdf.sh
> >> +./makehtml.sh $1
> >> +./makepdf.sh $1
> >>  zip $SPECDOC.zip $SPECDOC.pdf
> >>  echo Generated file $SPECDOC.zip
> >>  echo To change output file name, set SPECDOC environment variable
> >> diff --git a/makehtml.sh b/makehtml.sh
> >> index 45b7080..cf1a8d7 100755
> >> --- a/makehtml.sh
> >> +++ b/makehtml.sh
> >> @@ -1,7 +1,7 @@
> >>  #!/bin/sh
> >>  
> >>  SPECDOC=${SPECDOC:-`cat REVISION`}
> >> -./make-setup-generated.sh "$SPECDOC"
> >> +./make-setup-generated.sh "$SPECDOC" $1
> >>  
> >>  cp virtio-html.tex $SPECDOC.tex
> >>  
> >> diff --git a/makepdf.sh b/makepdf.sh
> >> index 9cae903..bdfb8e5 100755
> >> --- a/makepdf.sh
> >> +++ b/makepdf.sh
> >> @@ -1,7 +1,7 @@
> >>  #!/bin/sh
> >>  
> >>  SPECDOC=${SPECDOC:-`cat REVISION`}
> >> -./make-setup-generated.sh "$SPECDOC"
> >> +./make-setup-generated.sh "$SPECDOC" $1
> >>  
> >>  rm $SPECDOC.aux $SPECDOC.pdf $SPECDOC.out
> >>  xelatex --jobname $SPECDOC virtio.tex
> >> -- 
> >> 2.47.3
> >> 
> 
> -- 
> Alex Bennée
> Virtualisation Tech Lead @ Linaro

Re: [PATCH v2 08/10] make-setup-generated: optionally add GIT metadata

[Alex Bennée]

"Michael S. Tsirkin" <mst@redhat.com> writes:

> On Fri, Oct 10, 2025 at 02:10:25PM +0100, Alex Bennée wrote:
>> "Michael S. Tsirkin" <mst@redhat.com> writes:
>> 
>> > On Fri, Oct 10, 2025 at 12:20:08PM +0100, Alex Bennée wrote:
>> <snip>
>> >> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>> >> Message-ID: <20251008145916.2626143-8-alex.bennee@linaro.org>
>> >
>> > Pls avoid Message-ID trailers in patches you post. It's really
>> > confusing.
>> 
>> That was added by b4 - I can add a .b4-config to stop that happening
>> accidentally. I see the git history has Links instead, e.g.:
>> 
>>  Link: https://lore.kernel.org/r/20250305164546.1484029-1-mvaralar@redhat.com
>> 
>> is that OK?
>
> No, please don't add links for no point. Add a link if you are
> linking to some relevant discussion.
>
> When maintainers apply patches they can have b4 add
> message id in b4 am/shazam command. It's not the default though
> and that is maintainer flow not contributor flow.

It turned out I had:

[am]
        messageid = true

in my global config. I've dropped that and made it local for repos now.

>
>
> Parav started adding these links automatically with -l, I personally
> prefer -i so that links have meaning. Not worth my time
> fighting about though.
>
>
>> >
>> >> ---
>> >>  make-setup-generated.sh | 32 ++++++++++++++++++++++++++++----
>> >>  makeall.sh              |  4 ++--
>> >>  makehtml.sh             |  2 +-
>> >>  makepdf.sh              |  2 +-
>> >>  4 files changed, 32 insertions(+), 8 deletions(-)
>> >> 
>> >> diff --git a/make-setup-generated.sh b/make-setup-generated.sh
>> >> index 2c5c7f8..8d33ac5 100755
>> >> --- a/make-setup-generated.sh
>> >> +++ b/make-setup-generated.sh
>> >> @@ -1,16 +1,31 @@
>> >>  #! /bin/sh
>> >> +#
>> >> +# Generate version and metadata preamble for the document
>> >> +#
>> >>  
>> >>  DATESTR=${DATESTR:-`cat REVISION-DATE 2>/dev/null`}
>> >> -if [ x"$DATESTR" = x ]; then
>> >> -    ISODATE=`git show --format=format:'%cd' --date=iso | head -n 1`
>> >> -    DATESTR=`date -d "$DATE" +'%d %B %Y'`
>> >> +
>> >> +# If a second argument is passed we extract what we can from git
>> >> +# metadata (closest lightweight tag) and local tree status. This
>> >> +# allows locally generated copies to be tagged appropriately.
>> >> +#
>> >> +# The formal build process skips this.
>> >> +if ! test -z "$2"; then
>> >> +    TAG=$(git describe --dirty --tags)
>> >> +    # base date on now
>> >> +    DATESTR=$(date +'%d %B %Y')
>> >> +    COMMIT=$(git rev-parse --short HEAD)
>> >> +
>> >> +    # Finally check if we have un-committed changes in the tree
>> >> +    if ! git diff-index --quiet HEAD -- ; then
>> >> +        COMMIT="$COMMIT with local changes"
>> >> +    fi
>> >>  fi
>> >>  
>> >>  case "$1" in
>> >>      *-wd*)
>> >>  	STAGE=wd
>> >>  	STAGENAME="Working Draft"
>> >> -	WORKINGDRAFT=`basename "$1" | sed 's/.*-wd//'`
>> >>  	;;
>> >>      *-os*)
>> >>  	STAGE=os
>> >
>> > This is used in the generated latex:
>> > make-setup-generated.sh:\newcommand{\virtioworkingdraft}{$WORKINGDRAFT}
>> >
>> > Are you sure output for a wd is unaffected?
>> > We still need to be able to generate these for the TC process.
>> >
>> >
>> >> @@ -41,6 +56,15 @@ esac
>> >>  
>> >>  VERSION=`echo "$1"| sed -e 's/virtio-v//' -e 's/-.*//'`
>> >>  
>> >> +#
>> >> +# Finally if we are building a local draft copy append the commit
>> >> +# details to the end of the working draft
>> >> +#
>> >> +if ! test -z "$COMMIT" ; then
>> >> +    STAGEEXTRATITLE="$STAGEEXTRATITLE (@ git $COMMIT)"
>> >> +fi
>> >> +
>> >> +
>> >>  #Prepend OASIS unless already there
>> >>  case "$STAGENAME" in
>> >>  	OASIS*)
>> >> diff --git a/makeall.sh b/makeall.sh
>> >> index 37e6c34..5f5d5dc 100755
>> >> --- a/makeall.sh
>> >> +++ b/makeall.sh
>> >> @@ -3,8 +3,8 @@
>> >>  export SPECDOC=${SPECDOC:-`cat REVISION`}
>> >>  export DATESTR=${DATESTR:-`cat REVISION-DATE`}
>> >>  ./makezip.sh
>> >> -./makehtml.sh
>> >> -./makepdf.sh
>> >> +./makehtml.sh $1
>> >> +./makepdf.sh $1
>> >>  zip $SPECDOC.zip $SPECDOC.pdf
>> >>  echo Generated file $SPECDOC.zip
>> >>  echo To change output file name, set SPECDOC environment variable
>> >> diff --git a/makehtml.sh b/makehtml.sh
>> >> index 45b7080..cf1a8d7 100755
>> >> --- a/makehtml.sh
>> >> +++ b/makehtml.sh
>> >> @@ -1,7 +1,7 @@
>> >>  #!/bin/sh
>> >>  
>> >>  SPECDOC=${SPECDOC:-`cat REVISION`}
>> >> -./make-setup-generated.sh "$SPECDOC"
>> >> +./make-setup-generated.sh "$SPECDOC" $1
>> >>  
>> >>  cp virtio-html.tex $SPECDOC.tex
>> >>  
>> >> diff --git a/makepdf.sh b/makepdf.sh
>> >> index 9cae903..bdfb8e5 100755
>> >> --- a/makepdf.sh
>> >> +++ b/makepdf.sh
>> >> @@ -1,7 +1,7 @@
>> >>  #!/bin/sh
>> >>  
>> >>  SPECDOC=${SPECDOC:-`cat REVISION`}
>> >> -./make-setup-generated.sh "$SPECDOC"
>> >> +./make-setup-generated.sh "$SPECDOC" $1
>> >>  
>> >>  rm $SPECDOC.aux $SPECDOC.pdf $SPECDOC.out
>> >>  xelatex --jobname $SPECDOC virtio.tex
>> >> -- 
>> >> 2.47.3
>> >> 
>> 
>> -- 
>> Alex Bennée
>> Virtualisation Tech Lead @ Linaro

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

[PATCH v2 09/10] Makefile: add some simple make automations

[Alex Bennée]

This is just a helpful shortcut, especially when editing the documents
within an IDE which will offer up make targets to build the documents.

Reviewed-by: Parav Pandit <parav@nvidia.com>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-ID: <20251008145916.2626143-9-alex.bennee@linaro.org>
---
 Makefile | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100644 Makefile

diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..989b429
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,33 @@
+# -*- Mode: makefile -*-
+#
+# Basic Makefile to aid automation of document building
+#
+
+.PHONY: all local
+all:
+	./makeall.sh
+
+local-all:
+	./makeall.sh local
+
+.PHONY: html local-html
+
+html:
+	./makehtml.sh
+
+local-html:
+	./makehtml.sh local
+
+.PHONY: clean
+clean:
+	git clean -fd
+
+.PHONY: help
+help:
+	@echo "Build the VIRTIO specification documents."
+	@echo ""
+	@echo "Possible operations are:"
+	@echo
+	@echo " $(MAKE)         Build everything"
+	@echo " $(MAKE) html    Build local html"
+	@echo " $(MAKE) clean   Remove all intermediate files"
-- 
2.47.3

[PATCH v2 10/10] .github: add a runner to build the latest draft

[Alex Bennée]

This will run each time anything is pushed to the repository and store
the result in the release assets area of github. To see an example of
it in practice see the virtio-msg repo:

  https://github.com/Linaro/virtio-msg-spec/releases

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-ID: <20251008145916.2626143-10-alex.bennee@linaro.org>
---
 .github/workflows/deploy.yaml | 37 +++++++++++++++++++++++++++++++++++
 .github/workflows/test.yml    | 15 ++++++++++++++
 2 files changed, 52 insertions(+)
 create mode 100644 .github/workflows/deploy.yaml
 create mode 100644 .github/workflows/test.yml

diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml
new file mode 100644
index 0000000..fec4910
--- /dev/null
+++ b/.github/workflows/deploy.yaml
@@ -0,0 +1,37 @@
+name: Deploy current state
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: xu-cheng/texlive-action@v2
+        with:
+          scheme: full
+          run: |
+            apk add file font-liberation make zip
+            make local-all
+            echo ${{ github.sha }} > Release.txt
+
+      - name: Create Draft Release
+        id: create_release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{github.ref_name}}-${{ github.repository_owner }}-draft-v${{ github.run_number }}
+          release_name: Draft ${{ github.run_number }}
+          draft: false
+          prerelease: false
+
+      - name: Upload Release Asset
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ steps.create_release.outputs.upload_url }}
+          asset_path: virtio-v1.4-wd01.pdf
+          asset_name: ${{github.ref_name}}-${{ github.repository_owner }}-draft-v${{ github.run_number }}.pdf
+          asset_content_type: application/pdf
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
new file mode 100644
index 0000000..34f4f44
--- /dev/null
+++ b/.github/workflows/test.yml
@@ -0,0 +1,15 @@
+name: CI
+
+on: [pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: xu-cheng/texlive-action@v2
+        with:
+          scheme: full
+          run: |
+            apk add file make zip
+            make local-html
-- 
2.47.3

Re: [PATCH v2 10/10] .github: add a runner to build the latest draft

[Michael S. Tsirkin]

On Fri, Oct 10, 2025 at 12:20:10PM +0100, Alex Bennée wrote:
> This will run each time anything is pushed to the repository and store
> the result in the release assets area of github. To see an example of
> it in practice see the virtio-msg repo:
> 
>   https://github.com/Linaro/virtio-msg-spec/releases

Is this the PDF?

https://github.com/Linaro/virtio-msg-spec/releases/download/virtio-msg-rfc1-Linaro-draft-v14/virtio-msg-rfc1-Linaro-draft-v14.pdf


Some comments:
I suggest removing the version (e.g. replace with X.X)
Replacing "Working Draft" with just "Draft"
Maye stick the hash there too?


I also see front page corruption:
driver listing overlaps with related work.






> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Message-ID: <20251008145916.2626143-10-alex.bennee@linaro.org>
> ---
>  .github/workflows/deploy.yaml | 37 +++++++++++++++++++++++++++++++++++
>  .github/workflows/test.yml    | 15 ++++++++++++++
>  2 files changed, 52 insertions(+)
>  create mode 100644 .github/workflows/deploy.yaml
>  create mode 100644 .github/workflows/test.yml
> 
> diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml
> new file mode 100644
> index 0000000..fec4910
> --- /dev/null
> +++ b/.github/workflows/deploy.yaml
> @@ -0,0 +1,37 @@
> +name: Deploy current state
> +
> +on: [push]
> +
> +jobs:
> +  build:
> +    runs-on: ubuntu-latest
> +    steps:
> +      - uses: actions/checkout@v4
> +      - uses: xu-cheng/texlive-action@v2
> +        with:
> +          scheme: full
> +          run: |
> +            apk add file font-liberation make zip
> +            make local-all
> +            echo ${{ github.sha }} > Release.txt
> +
> +      - name: Create Draft Release
> +        id: create_release
> +        uses: actions/create-release@v1
> +        env:
> +          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
> +        with:
> +          tag_name: ${{github.ref_name}}-${{ github.repository_owner }}-draft-v${{ github.run_number }}
> +          release_name: Draft ${{ github.run_number }}
> +          draft: false
> +          prerelease: false
> +
> +      - name: Upload Release Asset
> +        uses: actions/upload-release-asset@v1
> +        env:
> +          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
> +        with:
> +          upload_url: ${{ steps.create_release.outputs.upload_url }}
> +          asset_path: virtio-v1.4-wd01.pdf
> +          asset_name: ${{github.ref_name}}-${{ github.repository_owner }}-draft-v${{ github.run_number }}.pdf
> +          asset_content_type: application/pdf
> diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
> new file mode 100644
> index 0000000..34f4f44
> --- /dev/null
> +++ b/.github/workflows/test.yml
> @@ -0,0 +1,15 @@
> +name: CI
> +
> +on: [pull_request]
> +
> +jobs:
> +  build:
> +    runs-on: ubuntu-latest
> +    steps:
> +      - uses: actions/checkout@v4
> +      - uses: xu-cheng/texlive-action@v2
> +        with:
> +          scheme: full
> +          run: |
> +            apk add file make zip
> +            make local-html
> -- 
> 2.47.3
> 

Re: [PATCH v2 10/10] .github: add a runner to build the latest draft

[Alex Bennée]

"Michael S. Tsirkin" <mst@redhat.com> writes:

> On Fri, Oct 10, 2025 at 12:20:10PM +0100, Alex Bennée wrote:
>> This will run each time anything is pushed to the repository and store
>> the result in the release assets area of github. To see an example of
>> it in practice see the virtio-msg repo:
>> 
>>   https://github.com/Linaro/virtio-msg-spec/releases
>
> Is this the PDF?
>
> https://github.com/Linaro/virtio-msg-spec/releases/download/virtio-msg-rfc1-Linaro-draft-v14/virtio-msg-rfc1-Linaro-draft-v14.pdf
>
>
> Some comments:
> I suggest removing the version (e.g. replace with X.X)

Isn't the closest version still useful (to know its not based on a
really old version of the spec)?

> Replacing "Working Draft" with just "Draft"
> Maye stick the hash there too?

I've gone with:

  Unofficial Draft (@ git 8c7a1c3 with local changes)

to make it clear its outside of the normal OASIS stats.

> I also see front page corruption:
> driver listing overlaps with related work.

I think that predates my changes - I built from current HEAD and it has
the some overlap.

For the unofficial draft should we just elide the stage information
entirely as the links it generates don't point anywhere?

>
>
>
>
>
>
>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>> Message-ID: <20251008145916.2626143-10-alex.bennee@linaro.org>
>> ---
>>  .github/workflows/deploy.yaml | 37 +++++++++++++++++++++++++++++++++++
>>  .github/workflows/test.yml    | 15 ++++++++++++++
>>  2 files changed, 52 insertions(+)
>>  create mode 100644 .github/workflows/deploy.yaml
>>  create mode 100644 .github/workflows/test.yml
>> 
>> diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml
>> new file mode 100644
>> index 0000000..fec4910
>> --- /dev/null
>> +++ b/.github/workflows/deploy.yaml
>> @@ -0,0 +1,37 @@
>> +name: Deploy current state
>> +
>> +on: [push]
>> +
>> +jobs:
>> +  build:
>> +    runs-on: ubuntu-latest
>> +    steps:
>> +      - uses: actions/checkout@v4
>> +      - uses: xu-cheng/texlive-action@v2
>> +        with:
>> +          scheme: full
>> +          run: |
>> +            apk add file font-liberation make zip
>> +            make local-all
>> +            echo ${{ github.sha }} > Release.txt
>> +
>> +      - name: Create Draft Release
>> +        id: create_release
>> +        uses: actions/create-release@v1
>> +        env:
>> +          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
>> +        with:
>> +          tag_name: ${{github.ref_name}}-${{ github.repository_owner }}-draft-v${{ github.run_number }}
>> +          release_name: Draft ${{ github.run_number }}
>> +          draft: false
>> +          prerelease: false
>> +
>> +      - name: Upload Release Asset
>> +        uses: actions/upload-release-asset@v1
>> +        env:
>> +          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
>> +        with:
>> +          upload_url: ${{ steps.create_release.outputs.upload_url }}
>> +          asset_path: virtio-v1.4-wd01.pdf
>> +          asset_name: ${{github.ref_name}}-${{ github.repository_owner }}-draft-v${{ github.run_number }}.pdf
>> +          asset_content_type: application/pdf
>> diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
>> new file mode 100644
>> index 0000000..34f4f44
>> --- /dev/null
>> +++ b/.github/workflows/test.yml
>> @@ -0,0 +1,15 @@
>> +name: CI
>> +
>> +on: [pull_request]
>> +
>> +jobs:
>> +  build:
>> +    runs-on: ubuntu-latest
>> +    steps:
>> +      - uses: actions/checkout@v4
>> +      - uses: xu-cheng/texlive-action@v2
>> +        with:
>> +          scheme: full
>> +          run: |
>> +            apk add file make zip
>> +            make local-html
>> -- 
>> 2.47.3
>> 

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

Re: [PATCH v2 10/10] .github: add a runner to build the latest draft

[Michael S. Tsirkin]

On Fri, Oct 10, 2025 at 02:58:53PM +0100, Alex Bennée wrote:
> "Michael S. Tsirkin" <mst@redhat.com> writes:
> 
> > On Fri, Oct 10, 2025 at 12:20:10PM +0100, Alex Bennée wrote:
> >> This will run each time anything is pushed to the repository and store
> >> the result in the release assets area of github. To see an example of
> >> it in practice see the virtio-msg repo:
> >> 
> >>   https://github.com/Linaro/virtio-msg-spec/releases
> >
> > Is this the PDF?
> >
> > https://github.com/Linaro/virtio-msg-spec/releases/download/virtio-msg-rfc1-Linaro-draft-v14/virtio-msg-rfc1-Linaro-draft-v14.pdf
> >
> >
> > Some comments:
> > I suggest removing the version (e.g. replace with X.X)
> 
> Isn't the closest version still useful (to know its not based on a
> really old version of the spec)?

Not sure. E.g. in this case this is *before* 1.4 and later one
will maybe be *after* 1.4, and not sure we'll remember to update.
Just worried people will get confused. Not critical I guess...
Maybe stick something else in there to make it clear?  X.1.4 ?

> > Replacing "Working Draft" with just "Draft"
> > Maye stick the hash there too?
> 
> I've gone with:
> 
>   Unofficial Draft (@ git 8c7a1c3 with local changes)
> 
> to make it clear its outside of the normal OASIS stats.

Sounds good. Maybe "ud" in the file name then like we did
for wd?

> > I also see front page corruption:
> > driver listing overlaps with related work.
> 
> I think that predates my changes - I built from current HEAD and it has
> the some overlap.

No, it's another problem with the toolchain used - I built it on latest
fedora and it does not have this issue.

> For the unofficial draft should we just elide the stage information
> entirely as the links it generates don't point anywhere?

I wouldn't bother too much and after all the point is to
speed up development so it's useful to make it look
close to what the official one will look like.

> >
> >
> >
> >
> >
> >
> >> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> >> Message-ID: <20251008145916.2626143-10-alex.bennee@linaro.org>
> >> ---
> >>  .github/workflows/deploy.yaml | 37 +++++++++++++++++++++++++++++++++++
> >>  .github/workflows/test.yml    | 15 ++++++++++++++
> >>  2 files changed, 52 insertions(+)
> >>  create mode 100644 .github/workflows/deploy.yaml
> >>  create mode 100644 .github/workflows/test.yml
> >> 
> >> diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml
> >> new file mode 100644
> >> index 0000000..fec4910
> >> --- /dev/null
> >> +++ b/.github/workflows/deploy.yaml
> >> @@ -0,0 +1,37 @@
> >> +name: Deploy current state
> >> +
> >> +on: [push]
> >> +
> >> +jobs:
> >> +  build:
> >> +    runs-on: ubuntu-latest
> >> +    steps:
> >> +      - uses: actions/checkout@v4
> >> +      - uses: xu-cheng/texlive-action@v2
> >> +        with:
> >> +          scheme: full
> >> +          run: |
> >> +            apk add file font-liberation make zip
> >> +            make local-all
> >> +            echo ${{ github.sha }} > Release.txt
> >> +
> >> +      - name: Create Draft Release
> >> +        id: create_release
> >> +        uses: actions/create-release@v1
> >> +        env:
> >> +          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
> >> +        with:
> >> +          tag_name: ${{github.ref_name}}-${{ github.repository_owner }}-draft-v${{ github.run_number }}
> >> +          release_name: Draft ${{ github.run_number }}
> >> +          draft: false
> >> +          prerelease: false
> >> +
> >> +      - name: Upload Release Asset
> >> +        uses: actions/upload-release-asset@v1
> >> +        env:
> >> +          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
> >> +        with:
> >> +          upload_url: ${{ steps.create_release.outputs.upload_url }}
> >> +          asset_path: virtio-v1.4-wd01.pdf
> >> +          asset_name: ${{github.ref_name}}-${{ github.repository_owner }}-draft-v${{ github.run_number }}.pdf
> >> +          asset_content_type: application/pdf
> >> diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
> >> new file mode 100644
> >> index 0000000..34f4f44
> >> --- /dev/null
> >> +++ b/.github/workflows/test.yml
> >> @@ -0,0 +1,15 @@
> >> +name: CI
> >> +
> >> +on: [pull_request]
> >> +
> >> +jobs:
> >> +  build:
> >> +    runs-on: ubuntu-latest
> >> +    steps:
> >> +      - uses: actions/checkout@v4
> >> +      - uses: xu-cheng/texlive-action@v2
> >> +        with:
> >> +          scheme: full
> >> +          run: |
> >> +            apk add file make zip
> >> +            make local-html
> >> -- 
> >> 2.47.3
> >> 
> 
> -- 
> Alex Bennée
> Virtualisation Tech Lead @ Linaro

Re: [PATCH v2 00/10] QoL tweaks and github action

[Michael S. Tsirkin]

On Fri, Oct 10, 2025 at 12:20:00PM +0100, Alex Bennée wrote:
> Some of these patches I've posted before. Along with general
> quality of life tweaks to the build scripts we also introduce a github
> workflow to build and publish the current working draft of the spec.
> 
> I also fixed a build regression with htlatex which became apparent
> when I upgraded to Debian Trixie with a newer htlatex build.

thanks for working on this!
I sent some questions and comments but generally this
is very helpful. Thanks!

> v2
> 
>   - added README.md cleanup
>   - applied r-b tags
> 
> The following still need review:
> 
>   .github: add a runner to build the latest draft
>   make-setup-generated: optionally add GIT metadata
>   virtio-html.cfg: implement workaround for htlatex regression
>   specvars.tex: properly wrap arguments to \urldef
>   README.md: convert embedded html to proper MarkDown
>   LICENSE.md: convert html to proper MarkDown
> 
> Alex.
> 
> Alex Bennée (10):
>   LICENSE.md: convert html to proper MarkDown
>   README.md: convert embedded html to proper MarkDown
>   REVISION: update to 1.4-wd01
>   .gitpublish: update base to current working branch
>   virtio-html.tex: sort package list
>   specvars.tex: properly wrap arguments to \urldef
>   virtio-html.cfg: implement workaround for htlatex regression
>   make-setup-generated: optionally add GIT metadata
>   Makefile: add some simple make automations
>   .github: add a runner to build the latest draft
> 
>  .github/workflows/deploy.yaml |  37 ++++
>  .github/workflows/test.yml    |  15 ++
>  .gitpublish                   |   2 +-
>  LICENSE.md                    |   8 +-
>  Makefile                      |  33 +++
>  README.md                     | 387 +++++++++++++---------------------
>  REVISION                      |   2 +-
>  make-setup-generated.sh       |  32 ++-
>  makeall.sh                    |   4 +-
>  makehtml.sh                   |   2 +-
>  makepdf.sh                    |   2 +-
>  specvars.tex                  |  14 +-
>  virtio-html.cfg               |   3 +-
>  virtio-html.tex               |  30 +--
>  14 files changed, 298 insertions(+), 273 deletions(-)
>  create mode 100644 .github/workflows/deploy.yaml
>  create mode 100644 .github/workflows/test.yml
>  create mode 100644 Makefile
> 
> -- 
> 2.47.3
>