|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [Xen-changelog] [xen master] docs: Provide support-matrix-generate, to generate a support matrix in HTML
commit 945e80a7301f9ed13d667b635b8a982b8928c3b4
Author: Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
AuthorDate: Wed Apr 11 11:42:27 2018 +0100
Commit: Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>
CommitDate: Thu Apr 12 16:13:49 2018 +0100
docs: Provide support-matrix-generate, to generate a support matrix in HTML
This archaeology script:
- figures out what the current and previous Xen versions were
- looks for appropriate git branches for them
- finds SUPPORT.md for each one
- feeds its findings to parse-support-md
We do not intend to integrate this into docs/Makefile, because it
relies on the git history. Instead, we will take the rune provided in
the head comment and paste a variant of it into an appropriate cronjob
on xenbits.
Signed-off-by: Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>
Release-acked-by: Juergen Gross <jgross@xxxxxxxx>
Acked-by: Lars Kurth <lars.kurth@xxxxxxxxxx>
---
v3: Provide -D option.
---
.gitignore | 1 +
docs/misc/support-matrix-head.html | 41 ++++++++
docs/support-matrix-generate | 186 +++++++++++++++++++++++++++++++++++++
3 files changed, 228 insertions(+)
diff --git a/.gitignore b/.gitignore
index cd57530cba..7004349d5a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -43,6 +43,7 @@ config/Paths.mk
build-*
dist/*
+docs/tmp.*
docs/html/
docs/man/xl.cfg.pod.5
docs/man/xl.pod.1
diff --git a/docs/misc/support-matrix-head.html
b/docs/misc/support-matrix-head.html
new file mode 100644
index 0000000000..7cc27765aa
--- /dev/null
+++ b/docs/misc/support-matrix-head.html
@@ -0,0 +1,41 @@
+<html>
+ <head>
+ <title>Xen versions and feature support matrix</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ </head>
+ <body>
+ <h1>Xen versions and features support matrix</h1>
+
+ This table summarises the support status of Xen releases,
+ and of individual features within each release.
+
+ <h2>Important notes</h2>
+
+ The matrix is extracted automatically
+ from the formal support status documents
+ in each Xen release.
+ The full formal support status document
+ is linked to from the column heading for each version.
+
+ <p>
+ The individual entries are summaries;
+ where a specific entry has more information in the full
+ document a link, denoted [*], is provided.
+ The statuses Supported, Experimental, and so on,
+ are likewise defined in the full document.
+
+ <p>
+ Sometimes the same feature, or a similar feature,
+ is named differently
+ in the documentation for different releases.
+ In such cases the table will show it as
+ two separate features,
+ with a discontinuity in support,
+ even though support may have been continuous.
+
+ <p>
+ The support status of versions earlier than listed here
+ is documented
+ <a href="https://wiki.xenproject.org/wiki/Xen_Project_Release_Features";>on
the wiki</a>.
+
+ <h2>Support Matrix</h2>
diff --git a/docs/support-matrix-generate b/docs/support-matrix-generate
new file mode 100755
index 0000000000..b5ce3f48b3
--- /dev/null
+++ b/docs/support-matrix-generate
@@ -0,0 +1,186 @@
+#!/bin/bash
+
+# usage:
+# cd xen.git
+# docs/support-matrix-generate [-D] \
+# refs/remotes/origin/master \
+# https://xenbits.xen.org/docs/unstable/SUPPORT.html \
+# refs/remotes/origin/stable-NN \
+# https://xenbits.xen.org/docs/NN-testing/SUPPORT.html \
+#
+# NN is a *literal* in the above rune! It will be substituted with
+# the appropriate version number.
+#
+# The idea is that we use staging's version of this script, and it
+# looks into the git history and various git remote tracking refs to
+# find the various versions of SUPPORT.md.
+#
+# The arguments specify the git refs to look in, and also the URLs for
+# the SUPPORT.html (which are needed so that we can make
+# cross-reference links). We provide the ref and url (i) for unstable
+# (ii) in template form for all previous versions.
+
+# Algorithm:
+#
+# We start with `refs/remotes/origin/master' and process its
+# SUPPORT.md into json.
+#
+# Then we try to find the next previous revision. This is done by
+# extracting the current version number from xen/Makefile. (We make
+# some slight assumption about how xen/Makefile's xenversion target
+# works, because we want to be able to do this without checking out
+# the whole tree for the version in question.) Then we use git log on
+# xen/Makefile to try to find a commit where the version changed.
+# This gives us the previous version number, NN.
+#
+# That is substituted into the `refs/remotes/origin/stable-NN'
+# argument to get the tip of the relevant branch. That in turns
+# contains another SUPPORT.md. We keep going until either the ref
+# itself is missing, or we get to a ref with no SUPPORT.md.
+
+set -e
+set -o posix
+set -o pipefail
+
+fail () { echo >&2 "$0: $1"; exit 12; }
+
+args=()
+
+case "$1" in
+ -D) args+=("$1"); shift ;;
+ -*) fail 'bad usage' ;;
+ --) shift; break ;;
+esac
+
+case "$#" in
+ 4) ;;
+ *) fail 'bad usage' ;;
+esac
+
+current_ref=$1
+current_url=$2
+pattern_ref=$3
+pattern_url=$4
+
+tmp_prefix="docs/tmp.support-matrix"
+tmp_mdfile="$tmp_prefix.md"
+tmp_revisions="$tmp_prefix.revisions.html"
+
+versionfile=xen/Makefile
+tmp_versionfile="$tmp_prefix.xen.make"
+
+cat docs/misc/support-matrix-head.html
+
+debug () {
+ echo "<!-- $* -->"
+}
+
+select_commitish () {
+ commitish=$1
+ debug "select_commitish $commitish"
+ obj="$(printf "%s:SUPPORT.md" "$commitish")"
+ exists="$(printf "%s" "$obj" | git cat-file --batch-check)"
+ >"$tmp_mdfile"
+ case "$exists" in
+ *' missing')
+ rm "$tmp_mdfile"
+ ;;
+ *' blob '*)
+ git cat-file blob "$obj" >"$tmp_mdfile"
+ ;;
+ *) fail "?? $current_url $exists ?";;
+ esac
+}
+
+commitish_version () {
+ case "$commitish" in
+ refs/*)
+ # this is how to find out if a ref exists
+ local gfer=$(git for-each-ref "[r]${commitish#r}")
+ if [ "x$gfer" = x ]; then return; fi
+ ;;
+ esac
+
+ git cat-file blob "$commitish:$versionfile" >"$tmp_versionfile"
+ version=$(make --no-print-directory -C docs \
+ -f "${tmp_versionfile#docs/}" xenversion)
+ case "$version" in
+ *.*.*) version="${version%.*}" ;;
+ esac
+ printf "%s\n" "${version%%-*}"
+}
+
+exec 4>"$tmp_revisions"
+
+while true; do
+ select_commitish "$current_ref"
+ current_version=$(commitish_version)
+ debug "current_version=$current_version"
+
+ if ! [ -e "$tmp_mdfile" ]; then break; fi
+
+ cat >&4 <<END
+<tr>
+<td align="center">$current_version</td>
+END
+ git >&4 log -n1 --pretty=tformat:'
+<td><code>%ci</code></td>
+<td><code>%H</code></td>
+' "$current_ref"
+ cat >&4 <<END
+</tr>
+END
+
+ current_jsonfile="$tmp_prefix.$current_version.json"
+ pandoc -t json <"$tmp_mdfile" >"$current_jsonfile"
+
+ args+=("$current_jsonfile" "$current_url")
+
+ # find previous version
+ search_commit="$current_ref"
+ while true; do
+ search_commit=$(git-log --pretty=format:%H -n1 \
+ -G 'XEN.*VERSION' $search_commit -- $versionfile)
+ if ! [ "$search_commit" ]; then search_version=''; break; fi
+
+ search_commit="$search_commit~"
+ select_commitish "$search_commit"
+ search_version=$(commitish_version)
+ debug "search_version=$search_version"
+ if [ "x$search_version" != "x$current_version" ]; then break; fi
+ done
+
+ if [ "x$search_version" = x ]; then break; fi
+
+ # have found the previous version
+ current_ref=${pattern_ref/NN/$search_version}
+ current_url=${pattern_url/NN/$search_version}
+done
+
+debug "${args[*]}"
+docs/parse-support-md "${args[@]}"
+
+cat <<END
+ <h2>Source materials</h2>
+ Generated from xen.git
+ by docs/support-matrix-generate and docs/parse-support-md.
+ <p>
+ Input revisions of SUPPORT.md used:
+ <table>
+ <tr>
+ <th>Version</th>
+ <th align="left">Commit date</th>
+ <th align="left">Git commit</th>
+END
+
+cat "$tmp_revisions"
+
+generated=$(TZ=UTC date --iso-8601=minutes)
+
+cat <<END
+ </table>
+ <p>
+ Last checked/updated/regenerated: ${generated/T/ }
+ </body>
+</html>
+END
--
generated by git-patchbot for /home/xen/git/xen.git#master
_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/xen-changelog
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |