I’m with STUPID ⤴️

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.

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

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.