This is a summary of thoughts, tips & tricks for HCL maintainers based on my personal experience over the last few years.
HCL report contents (review & editing)
HCL reports are YAML files which need to be reviewed and edited before being committed to the qubes-hcl repository. Once committed GitHub pages and Jekyll magic will make them appear in the respective table on the website.
When I took over the maintenance of the HCL I spent some energy in unifying brand and model names so the table sorts nicely. The easiest way to continue this is to simply look at the filenames, brand and model names already in qubes-hcl and then make sure new commit conform to the same pattern.
Sometimes reporters go a bit freestyle with the report fields and part of the job is to edit them back into shape so they confirm nicely with the rest of the reports.
- layout: needs to always be ‘hcl’
- type: this should always be either ‘laptop’, ‘desktop’ or ‘motherboard’; technically ‘notebook’ will also land in the laptop table and ‘workstation’ will make it into the desktop table but I’ve decided to be restrictive here and always use ‘laptop’, ‘desktop’ or ‘motherboard’. Sometime users put other things in here with are obvious but the important thing is to catch reports that should be under ‘motherboard’ but the reporter has classified them as ‘desktop’. There is no benefit in having a one-off personally build computer in the desktop list.
- hvm, iommu, slat, tpm, remap … I’ve always left those alone except for obvious reported edits in book length. These should be something like ‘yes’, ‘no’, ‘unknown’
- brand: the brandname picked up by the tool is often very long and contains a lot that’s not needed (e.g. ‘corporation’) and not used when normal people talk about a brand. Please make sure to use the common, short form of the brand name as reflected in all the other existing
qubes-hclcommits. One exception to this is that HP is still listed as ‘Hewlett-Packard’. - model: often this contains the model name twice of with unimportant additions like ‘Notebook’ or ‘Two-In-One’ … the problem with those is that they take too much space in the table on the website and make things harder to read.
- bios: same thing, trim to the actual version / id
- cpu, cpu-short: just see how it’s done in the existing reports
- chipset, chipset-short: this one might be controversial
… with Intel chips the chipset-short is used to actually display the CPU architecture code name (e.g. ‘Sky Lake’). When a new generation comes along a simple search for the CPU name will get you to Intel’s website and they’ll list the code name as ‘formerly known as’. However, in 99% of the cases I’ve simple searched for the PCI ID in the existing reports and copied over the name (that’s way faster than looking it up and works as long as the already committed reports contain correct information). - gpu, gpu-short: same thing… Google it if you can’t find the PCI id in the existing reports but in 99% of cases you will find it
- memory, sci and usb … nothing to edit here except if the reporter when freestyle
- versions … this are the actual reports for different Qubes versions. Look e.g. at my T430 reports to see the effect. We don’t need a new file when there are new reports for a machine/reporter that’s already in the list.
- works: needs to always be ‘yes’, ‘no’ or ‘partial’. Starting with R4.1 ‘partial’ is used if sleep/wake doesn’t work … something that might need to be discussed as sleep/wake on Linux get’s from bad to worse over time.
- qubes, xen, kernel … nothing to change here
- remark: often contains nothing or too much to be useful in the table. In the later case there is a trick with HTML that can be inserted here linking to the original post to ‘read more’. Just search for ‘read more’ in existing reports to see how it’s done.
- credit: qubes-users reports get listed with whatever name shows in the From: field of the email and forum reports get listed with the alias including the
@sign
*link: the URL to the forum post (I’ve always shortened them to e.g.https://forum.qubes-os.org/t/12876/1) or the Google Groups link (the mirroring of the qubes-users mailing list inside the forum is too slow, infrequent and unreliable to use – I’ve tried). The Google Groups link contains a whole bunch of unneeded crap after the&that can safely be removed.
Committing
When I started out I had my own fork of qubes-hcl and then push PRs to qubes-hcl which @adw would review and eventually they showed up on the website. For this transition and if @marek is OK with it I can do the same review role that @adw did for me. After a while the project granted me direct commit rights, which might also happen at some point for the next maintainers.
Tips and tricks
yamllint does exactly what you think it does and I always ran it over the entire qubes-hcl repository before doing a commit. The repository actually contains a .yamllint configuration files that excludes the line length rule. I strongly recommend maintainers to continue to use this.
I’ve ended up using Visual Studio Code because it just worked that well. Hence qubes-hcl also contains a .vscode config directory with three files. extensions.json simply lists three extensions I’ve found extremely useful:
- Linter: does the same thing as
yamllintby painting little red lines under violations just as one is used to from spell checkers - Code Spell Checker: … well for spell checking (
settings.jsoncontains the spellings I’ve added) - Tasks: makes tasks appear in the status bar. In this case
yamllintso you can press it.
tasks.json defines the yamllint task, which is the default so alternatively to pressing the button in the status bar one can also use Ctrl+Alt+B to run it.
Thank you notes
I’ve made it a practice to send a quick note to the reporter once their report is available publicly.