Welcome to my web log. See the first post for an introduction. See the archive page for all posts. (There is an english language feed if you don't want to see Finnish.)

Archives Tags Moderation policy Main site

Me on Mastodon, for anything that is too small to warrant a blog post.

All content outside of comments is copyrighted by Lars Wirzenius, and licensed under a Creative Commons Attribution-Share Alike 3.0 Unported License. Comments are copyrighted by their authors. (No new comments are allowed.)

Would you be willing to try Subplot for acceptance testing for one of your real projects, and give us feedback? We're looking for two volunteers.

given a project
when it uses Subplot
then it is successful

Subplot is a tool for capturing and automatically verifying the acceptance criteria for a software project or a system, in a way that's understood by all stakeholders.

In a software project there are always more than one stakeholder. Even in a project one writes for oneself, there are two stakeholders: oneself, and that malicious cretin oneself-in-the-future. More importantly, though, there are typically stakeholders such as end users, sysadmins, clients, software architects, developers, and testers. They all need to understand what the software should do, and when it's in an acceptable state to be put into use: in other words, what the acceptance criteria are.

Crucially, all stakeholders should understand the acceptance criteria the same way, and also how to verify they are met. In an ideal situation, all verification is automated, and happens very frequently.

There are various tools for this, from generic documentation tooling (word processors, text editors, markup languages, etc) to test automation (Cucumber, Selenium, etc). On the one hand, documenting acceptance criteria in a way that all stakeholders understand is crucial: otherwise the end users are at risk of getting something that's not useful to help them, and the project is a waste of everyone's time and money. On the other hand, automating the verification of how acceptance criteria is met is also crucial: otherwise it's done manually, which is slow, costly, and error prone, which increases the risk of project failure.

Subplot aims to solve this by an approach that combines documentation tooling with automated verification.

  • The stakeholders in a project jointly produce a document that captures all relevant acceptance criteria and also describes how they can be verified automatically, using scenarios. The document is written using Markdown.

  • The developer stakeholders produce code to implement the steps in the scenarios. The Subplot approach allows the step implementations to be done in a highly cohesive, de-coupled manner, making such code usually be quite simple. (Test code should be your best code.)

  • Subplot's "docgen" program produces a typeset version as PDF or HTML. This is meant to be easily comprehensible by all stakeholders.

  • Subplot's "codegen" program produces a test program in the language used by the developer stakeholders. This test program can be run to verify that acceptance criteria are met.

Subplot started in in late 2018, and was initially called Fable. It is based on the yarn tool for the same purpose, from 2013. Yarn has been in active use all its life, if not popular outside a small circle. Subplot improves on yarn by improving document generation, markup, and decoupling of concerns. Subplot is not compatible with yarn.

Subplot is developed by Lars Wirzenius and Daniel Silverstone as a hobby project. It is free software, implemented in Rust, developed on Debian, and uses Pandoc and LaTeX for typesetting. The code is hosted on gitlab.com. Subplot verifies its own acceptance criteria. It is alpha level software.

We're looking for one or two volunteers to try Subplot on real projects of their own, and give us feedback. We want to make Subplot good for its purpose, also for people other than us. If you'd be willing to give it a try, start with the Subplot website, then tell us you're using Subplot. We're happy to respond to questions from the first two volunteers, and from others, time permitting. (The reality of life and time constraints is that we can't commit to supporting more people at this time.)

We'd love your feedback, whether you use Subplot or not.

Posted Sat Feb 15 18:48:00 2020 Tags:

I retired from Debian as a developer a year ago. I said then that it was because Debian wasn't fun anymore, but I didn't unpack that much. It's been long enough that I feel I can do that. I should've done it back then, but I wasn't strong enough.

A big part of Debian not being fun is that there's so much hatred in the project. There's people attacking others for who they are, be it women or trans or non-binary. There's people standing up to defend the attackers. Debian is just now going through another bout of that. It's sad and it's disgusting. And it reaffirms that I made the right decision getting out.

People denying other people their humanity, their very right to exist, is something Debian should not tolerate. I think Debian should exclude people who do that from the project. Likewise, people defending the right to deny others their humanity should equally unacceptable.

De-humanizing rhetoric isn't the only reason Debian stopped being fun. Everything else seems irrelevant, though. If people don't want others to even exist, there's no point in discussing minor points like improving a consensus building culture, paying off at least a noticeable part of the technical debt Debian carries from the past quarter century, or smoothing away some of the worst sources of friction in the development process of the project.

Stop the hatred. The good will follow.

Posted Sat Dec 21 10:13:00 2019 Tags:

I made a poll on the fediverse yesterday.

In an international context (e.g., company that works around the globe, or a free software project with participants from several continents), what's the right date format?

The options and results:

  • 80% — 2019-12-13
  • 11% — 19 December 2019
  • 9% — 13/12/2019
  • 0% — 12/13/2019

The one with the name of the month is a different date than the others. That was a typo; mea culpa. Nobody commented on that, though, and I doubt it affected the results.

Here's my commentary. It was a bit of a trick question. Sorry. The first two options are both unambiguous as to which part is day, month, and year. The last two are entirely ambiguous, and require contextual information to interpret correctly. Thus, even though the third option is closest to what I'm used to from my own culture, I think it's utterly unsuitable in an international context.

My own preference is to express the month as a word, or abbreviation, but in many cases being all numeric is easier.

The most important bit is to be clear and unambiguous. Sometimes that means getting used to an unfamiliar notation.

Posted Fri Dec 13 10:38:00 2019

I want to develop free software with people who lift up each other, and aren't arseholes.

A year ago I left Debian. The process is called retiring in Debian, and it's not final: if you do it in an orderly manner, you can come back again, and be re-instated as a Debian developer with a faster, more lightweight process than is used for entirely new developers. This was the third time I retired. The reasons were different than previously.

The first two times I retired because I was pursuing other passions, and did not feel I could give Debian even the minimal attention and effort required to keep a few minor, leaf packages maintained. This time, I retired because Debian was not fun; it was in fact becoming awful, and I didn't want to participate anymore.

Debian had stopped being fun for me in several ways. One was that the tools, file formats, and workflows Debian uses are getting a little archaic, and generally sub-optimal. Even mundane, everyday tasks involved much more friction than they should. Another is that making any large changes in Debian is too much of an effort, these days, partly because of inertia, partly because it involves so many people.

All of that could have been tolerable, if not for the people. Some of the nicest, most competent people I know work on Debian. It has been a privilege and a joy to work with them.

A few of the other people in Debian I don't want to be associated with in any way, any more.

Debian has some vocal people who treat other people in ways that I don't want to accept. I don't want to go into specifics, or names, because that's not going help me move forward.

This is of course not a new thing. Debian has had problems with people behaving badly for years. I may have contributed to that, passively if not actively. However, as I get older, the friction from dealing with abrasive people is sanding off what thick skin I may have had when younger.

As I get older, I am also learning that some of the things I thought were OK when I was younger, are in fact harmful to other people. I don't want to harm other people, and I don't want to participate in a project where some of the people insist on what I think is harmful behaviour, because they feel it's their right.

Long after I left Debian, RMS managed to collapse the reality distortion field that's been surrounding and protecting him for many years. The triggering event for this was comments he made in a context involving Jeffrey Epstein. The comments caused a public uproar, and as a result RMS resigned from role of president of the Free Software Foundation, which he founded. He is currently still the leader of the GNU project. A lot of people are religously defending RMS and attacking his detractors. I find this to be problematic.

LWN has an excellent article on the topic. RMS has been behaving in problematic ways for a long time. He's not been publicly confronted about it before, at the scale he has been now.

RMS has done some awesome things that he should be honoured for. He started the GNU project and gave it, and the world, a vision of being able to use computers whose entire software stack is free, and inventing copyleft, a legal tool to protect software freedom, as well as writing large amounts of the initial code in the GNU project. He has worked hard and long to help drive the vision of freedom into reality. For this, he shall always be remembered and revered.

That doesn't excuse bad behaviour, such as insisting on abortion jokes, making women feel unwelcome in the GNU project, or various other things. I'm not going to make a list of his shortcomings, because this isn't a critique of RMS specifically. The problem I want to discuss isn't RMS or his personal behaviour.

The problem I do want to discuss is that almost everywhere in the free and open source development communities there's a lot of harmful behavour, and tolerance of it.

Harmful behaviour comes in many forms. Some people, for example, say outright that they don't want women involved in free software development. Others attack gay, lesbian, trans, queer, black, old, young, Christian, Muslim, atheist, any other other group of people identified by whatever attribute the attacker happens to dislike. Yet others are more subtle, not attacking directly, but not giving people in the group they dislike the same chance to participate, learn, grow, and generally be the best person they can be in the context of free software development.

This doesn't just harm the groups of people being targeted. It harms others, who see it happen, and think they might be targeted too, later, maybe for some other reason. It harms reaching the vision of software freedom, because it shoves large parts of humanity outside the software freedom movement, robbing the movement from many voices and much effort. This makes it harder to achieve the vision.

Excluding people from the movement for irrelevant reasons also harms humanity in general. It propagates the hate, hurt, and harm that is emblematic of life and politics around the world. While the software freedom movement can't solve all of those problems, we can and should at least not make it worse.

What should we in the software freedom movement do about all this? I've come to a few conclusions so far, though my process to think about this is ongoing.

  • Most importantly, we need to stop being tolerant of intolerance and bad behaviour. It's time for all project, groups, and organisations in the movement to have and enforce at least a minimal level of civil behaviour. We are a movement consisting of many communities, and each community may want or need their own norms, and that's OK. Some norms may even be in conflict. That's also OK, if unfortunate.

    Some people react to this kind of suggestion with hyperbolic claims and conspiracy theories. I don't want to debate them. It's possible to discuss community norms in a civil and constructive way. I know this, because I've seen it happen many times. However, it requires all participants to at least agree that there's behaviour that's unwelcome, and not reject the notion of community norms outright.

  • I am by nature averse to conflicts. I will try to confront bad behaviour in the future, rather than slinking away and going elsewhere. I will at least speak out and say I think something is unacceptable, when I see it.

  • I think the era for dictatorial models of governance for large free software projects is over. For small projects, it's unavoidable, because there's only one person doing any development, but when a project grows, it doesn't work to have one person, or a small anointed group, making all decisions. It's time to have more democratic governance.

    There are technical decisions that probably can't be done well by letting everyone vote on them. However, every substantial project will have other decisions that the whole community around the project should have a say in. Voting on how to fix a bug may not be workable, but voting on the minimum criteria for determining if a bug fix is acceptable is. Should the project require adding a regression test for any bug found in production? Should any such test and bug fix be subjected to code review? Should such bugs and their fixes be documented, even announced, publicly or kept secret? How should security problems be handled?

    In Debian, one of the guiding principles is that those who do, decide. It seems time to involve those who use in the decision making process as well.

I can't force all communities in the software freedom movement to agree with me. Obviously not. I won't even try. I will, however, in the future be wary of joining dictatorial projects where bad behaviour is tolerated. I'm hoping this will have at least some effect.

What about you?

(My blog does not have comments, but you can respond to this fediverse thread: https://toot.liw.fi/@liw/103080486083100970.)

Posted Sun Nov 3 09:43:00 2019 Tags:

Measuring test coverage by measuring which parts of the code are executed tests is not useless, but it usually misses the point.

Tests are not meant to show the absence of bugs, but to show what aspects of a program or system work. (See my previous rant.) If your automated tests execute 90% of your code lines, is that good enough? It doesn't really tell you what is tested and, crucially, what isn't. Those using the software don't care about code lines. They care about being able to do the things they want to do. In other words, they care about use cases and acceptance criteria.

The 10% of code not covered by your tests? If users never exercise that code, it's dead code, and should probably be removed. If those lines keep crashing the program, producing wrong results, causing data loss, security problems, privacy leaks, or otherwise cause dissatisfaction, then that's a problem. How do you know?

Test coverage should be measuring use cases and acceptance criteria. These are often not explicit, or written down, or even known. In most projects there are a lot of acceptance criteria and use cases that are implicit, and only become explicit, when things don't work the way users want them to.

A realistic test coverage would be how many of the explicit, known, recorded use cases and acceptance criteria are tested by automated tests.

Use cases are not always acceptance criteria. Acceptance criteria are not always use cases. Both need to be captured during the development process, and ideally recorded as automated test cases.

Code coverage is most useful when the main user of a piece of code is a developer, usually the developer who writes or maintains the code. In this case, coverage helps ensure all interesting parts of the code are unit tested. The unit tests capture the use cases and acceptance criteria, in very fine-grained details.

Posted Sat Oct 12 16:20:00 2019 Tags:

Some irrelevant personal history follows, skip to the next heading if uninterested. I first learnt to touch type on a portable, mechanical typewriter in my early teens. It was a somewhat painful process: when I hit a key a little wrong, my finger would plunge between the keys into the internals of the typewriter, which was full of sharpish metal edges. I lost some blood to gain typing skills.

Typing on computers is a joy in comparison. However, there's big differences between different keyboards. Over the decades I've learnt to prefer some types over others. Overall, my preference is for keyboards with mechanical switches over more rubbery ones. I type better and faster and more accurately when my fingers can sense that a key has been pressed.

For some time I'd been using gaming PC keyboards with Cherry MX red switches. These are a joy to type on, but are quite noisy. I've also been curious about split keyboards. Earlier this year I heard of the Keyboardio Model01 keyboard, which started as a crowdfunded project. I was curious.

However, it's expensive, for me, and quite different from anything I'd ever used before, so I was hesitant to get one. Luckily, I was introduced online to one of the founders of Keyboardio, who said they'd enjoyed the book I wrote for the Linux Documentation Project in the 90s, and would like to donate a keyboard for me. Joy!


I've been using the keyboard for some weeks now. Initially, I only used it to learn to touch type all over again. Not only is the keyboard different from any I'd been using before, but it seemed better suited to the US qwerty layout than the Finnish one, so I've been learning both a new physical layout and a logical layout.

Also, I've been curious of using a US layout for programming for some time, and this is the perfect excuse to learn. Much fun. Luckily, it's not been actually painful, and I've not lost any blood this time.

Now that I'm getting a little closer to my previous typing speed of 60 words per minute on the new keyboard, it is time to write this review. I've never been a fast typist, but this speed seems to be fast enough that my brain doesn't get bored or frustrated waiting for my fingers to do their thing.

Good stuff:

  • It just works. Plug it in via USB, and start typing.
  • Typing feel is great. It's fairly quiet, thanks to using Matias Quiet Click key switches, instead of Cherry ones. Yet there's no doubt about having pressed a key.
  • Build quality is good. Feels solid. They call it heirloom-grade, and I can imagine this one lasting me decades.
  • The firmware is free software, hackable, and changing it does not void warranty. I've not managed to brick the device. It's basically an Arduino with a fancy peripheral.
  • Keyboard layout can be configured with the Chrysalis desktop software, without having to build and update a whole new firmware blob. I've used to convert what is normally num lock to be scroll lock, so I can use it as a compose key.

I don't really have complaints, but of course one can always whinge:

  • The Keyboardio website is a little disorganised and could be improved. There might be a need for a documentation project just for this keyboard and its firmware and associated software.
  • Oh boy does it take time and effort to learn to type all over again. Even if it's worth it, it's still frustrating to re-learn something I first learnt almost forty years ago.
  • I wasn't overly impressed with the bundled cables (USB-C and Ethernet), but they're easy enough to replace. I now have cables that are just the right length, even if it seems silly to use CAT7 to connect two halves of a keyboard.

Verdict: I like the keyboard. If I lost it, I'd want to buy a new one. If necessary, I'd write another book to get one.

Disclaimer: this review was not commissioned by Keyboardio. When they offered to gift me a keyboard, they made no condition or request or even hint that I should write a review. They only asked that if I didn't like it, I'd gift it forward to some young hacker who would put it into good use, but couldn't afford it themselves. Sorry, young hackers, I'm keeping it.

Posted Sat Oct 5 21:43:00 2019 Tags:

The reMarkable tablet is a 10" e-paper tablet on which you can read PDF and ePub files, and write on with the stylus that comes with the device. It has fundamentally changed how I read textbooks.

I used to collect books, and was proud of my library. I have a custom-made book case, with about 20 shelf meters of space. Not huge, but I curated my dead trees carefully.

I have for years not liked having paper books. They're expensive to store (need a larger home, and thus higher rent), and become quite heavy to carry (I've moved home more than twenty times in my life). For a decade now I've preferred e-books. However, Kindle devices, or their competitors, tend to be small, paperback size. That's no good for texts that have graphs, diagrams, tables. Worse, most e-book formats are reflowable, which is great for novels and straight prose, but not so good for textbooks or other works that need layout.

I have, over the years, bought a number of textbooks as PDFs. PDF is in many ways an excellent format for textbooks. However, I've lacked a convenient way to read them. Reading on a laptop screen is awkward, due to the small screen. Reading on an external monitor is uncomfortable, since it ties me to my desk. Also, it's very easy to be distracted when at my computer (IRC, the Fediverse, email, RSS, ... and if nothing else, there's a web browser and Wikipedia).

I bought the reMarkable tablet almost a year ago, after starting a new job, and getting my first couple of salaries. It's a little expensive, but I felt like splurging, and was in a privileged position to do so. I've not regretted it.

Things I especially like:

  • The screen is big enough for most books, and big enough for me to read A4 (or letter) sized documents without problems.

  • Writing is natural and smooth, almost exactly like writing on paper. The tablet seems to not have any trouble keeping up with the pen.

  • Did you know it's fun to scribble notes on books? It wasn't allowed when I was in school, since books were shared and often borrowed from the school. So much fun! Also, seems to make comprehension better for me.

  • There are no distractions on the device, except all the other books you've put there.

There are some things I don't much like, of course. They're not big enough to prevent me from using the device, and finding it a pleasure, but I feel I should mention them in case someone reading this is considering to buy one.

  • While the tablet keeps up with writing just fine, it's a little slow when jumping around a long document. It feels like it only caches a few pages in full, and thumbnails of the rest, if that, and has to re-render pages often. This makes jumping around a little tedious. I'm not sure why it doesn't cache more, since I have gigabytes of free space.

  • The software isn't free, and the APIs, file formats, and data structures are not documented. This makes it harder to, say, sync any new documents to the device automatically. I bet the company would get an enthusiastic developer community in no time, if they opened up the software. That seems like it would be a no-brainer, given they make their money from hardware sales and better software support would result in more hardware sold.

  • The way it renders PDF tables of content is ugly, hard to read, a little slow, and a little too easy to misnavigate.

  • The tablet does not follow intra-document links in PDFs. In some books this is annoying.

  • There's a bug in the firmware when exporting annotations you've made to a PDF with different sized pages. It turns out a lot of the books I've bought as PDF have a cover page that's of a different size to the interior pages, and the tablet exports annotations relative to the top left of the cover page, rather than the page where the annotations are.

Verdict: I like the tablet, and would buy a new one if I lost mine.

Posted Sun Sep 22 10:00:00 2019 Tags:

Recently I announced a tool for acceptance testing. It turned out that the name we'd chosen was already used by another testing tool, so we renamed ours. The new name is Subplot (the old name was Fable).

Work on the production implementation has started. If you are good at typography, help with automated typesetting of Subplot documents would be greatly appreciated. The goal: to use typography to make Subplot documents as easily understood and as effective at communicating acceptance criteria as possible.

Posted Tue Sep 17 09:09:00 2019 Tags:

Lars Wirzenius and Daniel Silverstone announce the Fable project.

given all stakeholders need to understand acceptance criteria
when Fable is used to document them
then all stakeholders understand them
and they can be automatically tested

Fable is a tool set for documenting acceptance criteria for a system, in a way that's understandable by all stakeholders, and for implementing automated tests to verify the criteria are being met.

See the Fable home page, including links to source code and Debian packages. There is a tutorial (PDF), examples, and documentation. Fable is free software, but doesn't constrain the license of the generated documentation or test programs.

Posted Sat Aug 24 09:44:00 2019 Tags:

Debian uses PGP keys of its uploading members to authenticate package uploads. The keys are stored in a keyring maintained by the keyring-maint team. The team also maintains a PGP keyserver, and new keys and signatures are uploaded there. The Debian keyserver gets new signatures from other keyservers, but only accepts signatures by keys already in the Debian keyring. New keys are accepted into the keyring manually, after a vetting process of the person. Updates from the Debian keyserver to the Debian keyring happen manually, roughly once a month. Only package uploads signed by keys in the Debian keyring get accepted by the Debian package archive.

The Debian package archive is signed by another key, securely maintained by the Debian FTP team. A copy of the public key is installed on every Debian machine, and updates to the key, as well as new keys, are distributed via package updates. This happens routinely in Debian.

Because of these reasons, Debian seems immune to the current attack on the SKS keyserver network, since Debian isn't getting those signatures, and the Debian package archive and updates to machines running Debian aren't getting the fraudulent signatures either.

(I've checked the above text with the keyring-maint team and they are OK with it.)

Posted Tue Jul 2 17:18:00 2019 Tags: