I have an idea. As serious and professional developers of serious and professional things, we 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, Pls. "I need this thing to work in both Debian- and Ubuntu-based environments" heh The reality is that we have to do workarounds for things that should "just STUPID.md Or .txt if you're that person. In a nutshell, a STUPID file documents all of the shenanigans that forwarn a STUPID.md is a project file that catalogues workarounds, patches, and The name is deliberately non-committal about whose fault any given entry is. 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. 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. 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. Fields appear in order: level-3 heading, file reference on its own line, 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) Entries should be grouped into sections if the project has distinct domains of The file must include a ## Fixed section at the bottom. When an upstream tool The file should be factual enough to be actionable. Tone is at the author's 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. New entries require a file and line reference so the workaround can be ## Fixed with the correction noted. "Hey, 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 In fact, the existence of a ## Fixed section, as noted above, is about going 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.