gesslar

Posted on Apr 19

I'm with STUPID ⤴️

#documentation

I have an idea.

As serious and professional developers of serious and professional things, we have all encountered the standard, boilerplatey documents in serious and professional projects.

Such files include, but are not limited to

README - project overview, install/usage instructions, badges
CONTRIBUTING - how to contribute, PR process, code style expectations
CHANGELOG - version history, what changed and when
LICENSE - the legal text (your beloved 0BSD)
CODE_OF_CONDUCT - community behaviour expectations
BUILD.someos - Build instructions for myriad OSes and environments

The last, BUILD.md, often documents dependencies and toolchain requirements, and if we're fortunate, does not include any gymnastics that upstream coerces us to perform to get their dependencies and toolchains to, at the very least, function in a not-so-unusual, if maybe not exactly idiomatic use case, because everything just works!

Pls.

"I need this thing to work in both Debian- and Ubuntu-based environments" because, at the end of the day "it's all Linux" and frankly, it's the same. Right?

heh

The reality is that we have to do workarounds for things that should "just work". And sometimes those workarounds are idiotic, necessary incantations that took 2 days, 4 robots, an invocation to a deity who really only exists as a hunky Harlequin jacket cover, and possibly too much bevvie. But the cost was real and we should document the what, the where, and the why. Because as serious and professional developers, while we don't go in and yoink out perfectly working code in favour of probably better code, and somehow nothing builds, it will surely serve someone new to a project to understand a purposeful block of Fragility as Infrastructure.

Introducing STUPID.md

Or .txt if you're that person.

In a nutshell, a STUPID file documents all of the shenanigans that forwarn a future version of you or your team or anybody who has just forked or cloned your project and may encounter some questionable or weird patterns that don't really seem like they should be a problem, but are.

Purpose

STUPID.md is a project file that catalogues workarounds, patches, and contortions that exist in a codebase not because they are correct, but because something else is more wrong. It is distinct from setup documentation (which explains what is expected) and from general developer notes (which explain intent). Its specific domain is the unexpected: the thing a future maintainer would remove in a cleanup pass, break the build, and spend hours discovering why it was there.

The name is deliberately non-committal about whose fault any given entry is. Some entries are upstream tools failing to handle a common case. Some are missing flags that weren't found in time. Some are the author's own doing. The file does not adjudicate blame — it documents cost.

When to add an entry

An entry belongs in STUPID.md if all of the following are true:

It is a workaround for something that should have been handled by an external tool, framework, or upstream dependency.
It looks wrong, or surprising, or unnecessarily complicated to someone reading it cold.
Removing it would break something, subtly or catastrophically.
It is not covered by setup documentation (prerequisites, toolchain requirements, environment configuration).

If a future contributor might reasonably "clean it up," it belongs here.

When not to add an entry

Normal build prerequisites and toolchain setup — those belong in BUILD.md, DEVELOPMENT.md, or equivalent.
Deliberate architectural decisions, even unusual ones — those belong in ARCHITECTURE.md or inline comments.
Workarounds for your own deliberate design choices — that's architecture, not stupidity. STUPID.md is for problems imposed from outside the codebase's own decisions.
Known bugs or planned improvements — those belong in your issue tracker.

Entry format

Each entry is a level-3 heading followed by the fields below.

Field	Required	Description
Heading	required	A short, plain-language description of what the workaround does. Not what caused it.
File reference	required	At least one `path/to/file:line` reference so the workaround can be located and verified.
Body	required	What the problem is, what tool or upstream is responsible (if known), and what the workaround does. Enough detail that a maintainer does not rediscover the problem from scratch.
Upstream reference	optional	A link to the issue, PR, or bug report that documents the upstream failure, if one exists.

Example entry

Fields appear in order: level-3 heading, file reference on its own line, body paragraph, then a See: line for the optional upstream reference.

### Blanket-disable WebKit's DMABUF renderer on Linux

`src-tauri/src/lib.rs:71-83`

The WebKit DMABUF renderer crashes on X11 + NVIDIA. We set
`WEBKIT_DISABLE_DMABUF_RENDERER=1` before Tauri spawns any threads,
because `std::env::set_var` is `unsafe` for exactly that reason.

See: [tauri-apps/tauri#8541](https://github.com/tauri-apps/tauri/issues/8541)

Document structure

Entries should be grouped into sections if the project has distinct domains of stupidity (e.g. build-time vs. runtime vs. packaging). A flat list is fine for smaller projects. Sections use level-2 headings.

The file must include a ## Fixed section at the bottom. When an upstream tool resolves a problem and the workaround is removed, the entry moves here rather than being deleted. Include the date the fix landed and what resolved it.

Fixes are worth celebrating.

Tone

The file should be factual enough to be actionable. Tone is at the author's discretion — dry, clinical, or gallows-humour are all fine — but each entry must contain enough detail that a future maintainer can understand the problem without reproducing it. Information without venting is fine; venting without information is not.

Relationship to other project files

File	Domain
`BUILD` / `DEVELOPMENT`	Setup steps and prerequisites. Expected friction. Not stupid.
`CONTRIBUTING`	How to participate. Process, not workarounds.
`CHANGELOG`	What changed between versions. `STUPID.md` tracks what stays broken.
Inline comments	Explain intent at the call site. `STUPID.md` explains why the call site exists at all.

Contributing to STUPID.md

New entries require a file and line reference so the workaround can be verified. Corrections are valid contributions: if an entry turns out to have a cleaner solution (a flag that does it properly, an upstream fix that landed), open a PR that moves the entry to ## Fixed with the correction noted. "Hey, there's a flag for that" is a perfectly good contribution.

Am I the problem?

Sometimes workarounds exist to work around our own idiocy and this is why STUPID.md is not an intrinsic blame machine. It is documentation of things we have done to get something to work.

In fact, the existence of a ## Fixed section, as noted above, is about going "YAY!" which can hit a lot harder when the blocker that existed upstream was our own brain.

Final note

This is a win-win document. We catalogue why we did something hopefully less dumb than something dumber that existed. And if/when upstream finally reconciles with reality, we remove the dumb, and move the annotation of the dumb to posterity.

DEV Community