DEV Community: Mara Averick

Write It Like C: What V8's Optimizing Compilers Explain About the Zen of stdlib

Mara Averick — Mon, 24 Aug 2026 14:15:34 +0000

JavaScript wasn't designed for numerical computing. There's one number type (a 64-bit float), no operator overloading, no control over memory layout, and a value model where every integer is, in principle, an object. And yet, on a modern V8, a tight loop over a Float64Array lands within a small constant factor of equivalent C—sometimes at basically the same speed. That's not an accident, and it's not free. It's the cumulative result of fifteen years of compiler engineering specifically aimed at recognizing, at runtime, that the dynamic-language source you wrote is in fact behaving like a statically-typed numerical kernel—and rewriting it as one.

If your first association with "V8" is horsepower and max towing capacity, the Zen of stdlib is going to read as an elegant list of design principles you're supposed to memorize. And it kind of is one—about two dozen entries. Some are about people (code is read more than it is written, be kind to your future self, tend to the garden), some are general engineering taste (don't be clever, complexity kills, simple is beautiful). Two are unmistakably about machines: write it like C, and avoid polymorphism by default, which the long form spells out as "monomorphic is best, polymorphic is not great, megamorphic is terrible." Those last three terms are counting how many different kinds of thing one spot in your code has had to handle: one, a handful, or more than the engine will keep track of.

What I didn't expect is how many of those middle entries are also about a machine. Don't be clever means something specific once you know what happens when you try to outsmart a speculative optimizer. Same with mistakes are infectious, fix them early, and stability is a feature. A lot of what looks like taste turns out to be doing real work.

I'm not a compiler engineer, I've never written a numerical kernel, and I don't write C. My job is making stdlib's conventions legible to people arriving at the codebase, and I couldn't explain half of these without knowing what V8 actually does with a loop—so I went and found out. The useful discovery, for anyone else who doesn't write C either: write it like C asks for less knowledge of C than you'd think. What it actually asks for is knowing what the optimizer is trying to prove. What follows is the map I wanted when I started, assembled from the V8 team's writing about their own pipeline and from asking stdlib maintainers why the code looks the way it does. You don't need to have gone spelunking inside V8 for it to make sense—I hadn't when I started.

The part that surprised me most: the rules have barely moved in a decade, while the machinery enforcing them has been rebuilt three or four times. That's why they're worth internalizing rather than looking up.

On other engines: this post is about V8. JavaScriptCore in Safari and SpiderMonkey in Firefox ship their own compiler architectures, and circle many of the same principles by different routes. V8 gets the attention here because it runs Chrome and it's the runtime under Node.js and Deno, so most stdlib code ends up executing on it. Where I could, I've stuck to general principles rather than V8-specific quirks, since those are the parts likely to travel.

A note on vocabulary

This post throws around terminology—hidden classes, shapes, inline caches, elements kinds, deoptimization—and uses some of it before explaining it. Don't worry—the explanations arrive later, where the terms are doing more work. If you'd rather have a running start, two pieces cover most of it:

Mathias Bynens — JavaScript engine fundamentals: Shapes and Inline Caches — hidden classes and inline caches, which is most of the vocabulary here; and
Mathias Bynens — Elements kinds in V8 — how V8 tracks what is inside an array.

Feeling a little out of your depth here is fine—I definitely did.

Why a numerical JavaScript lens?

Most V8-pipeline explainers target general-purpose JS frameworks, page-load metrics, or web-app responsiveness. The optimizations they highlight absolutely apply to numerical code—function inlining, hidden-class stability, megamorphic call sites all matter here. They just aren't the whole story for a Float64Array-bound inner loop.

Keep a loop like this one in mind:

function scale( x, out ) {
    for ( let i = 0; i < x.length; i++ ) {
        out[ i ] = x[ i ] * 2.0;
    }
}

Nothing about it is clever (which is the point). Assume x and out are Float64Arrays and that scale gets called thousands of times.

Four of the engine's questions matter much more for numerical work than they do for typical app code, and all four are about that loop. Each names something the optimizer is trying to prove, and each returns further down with the mechanism attached—so this is a map to come back to, not something to hold in your head now.

Boxing and unboxing. Does x[ i ] reach the multiply as a raw 64-bit float in a CPU register, or as a heap-allocated wrapper the engine reads through on every operation? Numerical code multiplies that difference by a million.
Elements kind. Is x's backing store (the memory the elements actually live in) a contiguous block of doubles, or a tagged array of generic JS values, where every slot has to carry its own type? V8 tracks this per array, and the loop reads through that store on every iteration.
Deoptimization. The optimizer bets that scale only ever sees Float64Array. What happens on the call that breaks the bet—when V8 has to throw the specialized code away? That bet gets tested constantly, because one kernel gets reused against different inputs all day long.
Tiering. V8 has four compilers rather than one, and they trade compile time against code quality. Does scale want the last cycle squeezed out of peak code, or to reach peak code fast enough that a Node service or notebook session spends most of its time there? That second case is the common one for numerical code.

Most of V8's recent architectural work comes back to one or another of these four: Sparkplug, Maglev, the Turboshaft intermediate representation (IR), mutable heap numbers.

A 15-year ladder

Today's V8 has four JavaScript execution tiers. It did not start there. Each addition responds to a specific gap left by the previous tier.

Crankshaft (2010–2017)

In December 2010, Google shipped Crankshaft, V8's first speculative optimizing compiler. Crankshaft was layered above V8's existing baseline compiler, Full-codegen: cold code ran there, and once a function got hot, V8 promoted it to Crankshaft for re-compilation against type assumptions. Crankshaft used two intermediate representations: a high-level static-single-assignment (SSA) graph called Hydrogen, and a lower-level form called Lithium. It leaned heavily on inline-cache feedback collected by the running baseline code.

Crankshaft is the V8 that stdlib-shaped JavaScript was first written against. Its rules still apply today—monomorphic call sites, stable hidden classes, no megamorphism, no surprise types. They were never about Crankshaft specifically; they described the underlying contract between dynamic source and a speculative optimizer. One of those terms is worth unpacking now: a hidden class is V8's internal record of an object's layout—which properties it has, in what order, at what offsets. Objects built the same way share one; code that only ever sees a single hidden class is code V8 can specialize hard. That's what monomorphic means (a fuller treatment comes below).

What Crankshaft was bad at, and what eventually retired it: keeping pace with new ECMAScript features. Generators, classes, destructuring, let/const, async functions—every one was either grudgingly supported through baseline-only paths or left unoptimized. The team had to add every new feature to both compilers—and to a third C++ runtime that the bytecode-less baseline compiler interacted with. That cost was suffocating the team.

Ignition + TurboFan (2016–2017)

Ignition shipped first, in 2016, as a bytecode interpreter—V8 hadn't previously had one. Ignition was motivated by memory, not speed: a bytecode interpreter's memory footprint is dramatically smaller than baseline-compiled machine code, which mattered enormously for the mobile devices Chrome was deploying on.¹ As a side effect, Ignition gave V8 a single canonical place where every JavaScript program existed in a stable, structured form before any compiler ever looked at it. That single canonical form is what made the next three tiers possible.

TurboFan shipped next, and in May 2017 V8 v5.9 made the new pipeline default: Ignition for first execution, TurboFan for hot functions. Crankshaft was then removed in v6.1, and Full-codegen followed in v6.2—the latter release alone deleted more than 30,000 lines of code. TurboFan introduced two big ideas:

A layered architecture with explicit phases (typing, simplification, lowering, scheduling, machine-specific instruction selection). Each supported CPU architecture needed only a few thousand lines of architecture-specific code, against more than ten thousand per chip architecture for Crankshaft.² The layering made it tractable to add new optimizations and new ES features.
A "sea of nodes" intermediate representation that lets the compiler reorder operations very freely, exposing more optimization opportunities than a strictly ordered control-flow graph would.

For numerical code, TurboFan was much better than Crankshaft at getting out of the way: it could see through more closures, inline more deeply, eliminate redundant hidden-class checks, and unbox numbers more aggressively. If your code was already monomorphic and shape-stable, TurboFan generated meaningfully tighter machine code than Crankshaft did.

Sparkplug (2021)

For the next four years, V8 was a two-tier system: Ignition → TurboFan. The gap between them was real. Ignition's bytecode dispatch is fast as interpreters go but pays a per-instruction decode cost; TurboFan only kicks in when a function has been called enough times to justify its compilation expense. Functions in the middle—called often enough to matter, not often enough to optimize—were stuck paying the interpreter tax indefinitely.

Sparkplug, shipped in V8 9.1 in 2021, fills that gap. It is a non-optimizing baseline JIT that compiles directly from Ignition bytecode in a single pass, with no IR, no type specialization, and no hidden-class-based fast paths. It defers most real work to the same builtins Ignition uses; what it eliminates is the per-bytecode dispatch overhead. Leszek Swirski's framing in the Sparkplug post is what made it click for me: a CPU is itself an interpreter for machine code, and Sparkplug is a "transpiler" from Ignition's bytecode to the CPU's. The function moves from running in an emulator to running natively, but the work it does in each instruction is roughly identical.

Sparkplug's stack frames are bit-compatible with Ignition's. Debuggers, profilers, and exception handlers don't need to know Sparkplug exists. That compatibility is also what makes mid-loop tier promotion (on-stack replacement) trivial: because the layout matches, the engine can compile a Sparkplug version of a hot loop and patch the stack frame in place.

For numerical code, Sparkplug mostly matters at the boundaries—for kernels that are called occasionally, and for code paths around the hot loop that handle argument validation and dispatch. The actual hot loop, if you wrote it well, will eventually get to TurboFan or Maglev. Sparkplug is what runs the rest while the type feedback accumulates.

Maglev (2023)

Maglev, introduced in Chrome M117 in 2023, is a mid-tier optimizing compiler slotted between Sparkplug and TurboFan. It uses the same type feedback TurboFan does, performs many of the same specializations, and emits real optimized machine code. The difference: Maglev compiles roughly 10× faster than TurboFan and 10× slower than Sparkplug, with code quality calibrated accordingly.³ Its IR is a traditional SSA-plus-CFG form—the program as an ordered graph of basic blocks (a control-flow graph, CFG) in which every value is assigned exactly once. TurboFan's sea of nodes goes the other way on ordering—operations float free of any fixed order, and the compiler works out afterward when each one happens. Fixing the order up front is what keeps Maglev's register allocation simple, and simple register allocation is most of why it compiles fast.

Maglev is the moment in the pipeline where speculative type specialization arrives. For numerical code that means two things become true simultaneously, and earlier in the warm-up curve than they used to:

Hidden-class checks get folded. Where a site has only ever seen Float64Array arguments, Maglev collapses the hidden-class guard and resolves the element-load to a direct memory offset. The same monomorphism rules that pay off at TurboFan now pay off at Maglev.
Representation selection runs. Maglev has an explicit phase that picks the in-register representation for every value: integer, float, or boxed object. A Float64Array element is unambiguously a float, so Maglev picks the right register kind immediately. A plain Array of mixed numbers and strings forces a conservative boxed representation through the whole loop. This is the moment unboxing actually happens.

A second consequence of Maglev shows up on the way back. The fall itself is unchanged: a deoptimization returns execution to Ignition, and the invocation that broke the bet finishes in the interpreter—off Maglev and off TurboFan alike, not one tier down. What Maglev changes is the recovery. Sparkplug's code is never discarded, so the next call starts in baseline machine code rather than in the interpreter, and the optimizing tier the function reaches on the way back up is Maglev rather than TurboFan. Older talks describe the deopt cliff as full machine code → interpreter, with a long crawl back. The drop is the same height; the climb out is much shorter.

Turboshaft (2023–2025), not an execution tier

Turboshaft is the one entry on this list that isn't a tier, which is why the count above stays at four. In 2023 V8 began an internal effort to migrate TurboFan off the sea-of-nodes IR onto a more conventional CFG-based form, called Turboshaft. The reasons were prosaic and accumulated over a decade: sea of nodes is flexible but cache-unfriendly (related operations end up scattered in memory), bugs are harder to investigate, and rewrite passes had grown gnarly. The blog post describing the move shipped in March 2025; by then the entire JavaScript backend of TurboFan had migrated. Compile times roughly halved versus the sea-of-nodes era.⁴

Turboshaft is invisible at the source level—the optimizations TurboFan does are still the optimizations it does—but it shifts the engineering economics. Faster compilation means functions reach optimized code sooner, so a bigger share of any run executes in fast code rather than warming up. For long-running Node services and notebook-style scientific JS, that compounds. It also makes future optimization work cheaper, which means more of it.

Putting the ladder back together

A simplified schematic of the modern pipeline, including deopts:

Every promotion is gated on type-feedback signals collected by the tiers below. Every deoptimization returns to the interpreter, whichever tier it left. The path each function takes is its own—there is no global compile pass—and a function's currently-running tier is observable with node --trace-opt and friends.

For numerical code: given enough warmup, an inner loop you care about will end up in TurboFan/Turboshaft (or Maglev, if it's not hot enough for TurboFan). The supporting code around it—argument validation, dispatch, the body of any function called occasionally—will sit at one of the lower tiers indefinitely. The discipline you apply to the hot loop pays off most at the top of the ladder; the discipline you apply to the supporting code pays off mostly by keeping a megamorphic inline-cache site or a hidden-class change from deoptimizing the hot loop.

One boundary worth naming: V8 also compiles WebAssembly, through its own baseline and optimizing tiers. It's a separate pipeline with a separate story, and out of scope here.

The representation primitives that make this work

The compiler tiers are the layer most people think about, but the value representation they operate on is doing just as much of the work. A handful of pieces show up in every V8 numerical-performance discussion.

SMI vs. HeapNumber

V8 uses pointer tagging. A 64-bit slot whose low bit is zero is a Small Integer (SMI)—a signed integer stored directly in the slot, no allocation, no indirection. The payload is 31-bit on builds with pointer compression and 32-bit on builds without. That's worth checking rather than assuming: Chrome enables pointer compression, official Node builds don't, so on Node 2**31 - 1 is still an SMI. node -p "process.config.variables.v8_enable_pointer_compression" answers it for your build. A slot whose low bit is one is a tagged pointer to a heap object. V8 stores any number that doesn't fit in the SMI range—floats included—as a HeapNumber: a heap-allocated wrapper containing a 64-bit double, referenced from the slot by a tagged pointer.

That's why the boxed vs. unboxed distinction matters. In Ignition and Sparkplug, every floating-point arithmetic operation reads through a HeapNumber wrapper, possibly allocates a new one for the result, and adds garbage-collection pressure. In Maglev or TurboFan, once the optimizer has stable feedback that a value is always a float, it strips the wrapper: the raw 64-bit value lives in a CPU floating-point register, and arithmetic compiles down to a single floating-point instruction. A tight loop of thousands of float operations collapses to bare register arithmetic. Without unboxing, every number in your hot loop allocates.

Pointer compression (V8 8.0, 2019)

Pointer compression shrinks every tagged slot from 64 bits to 32 by allocating all V8 objects within a 4 GB region and storing offsets rather than full pointers. The "base" half is shared per isolate; the "index" half is what gets stored. The headline number: heap memory dropped ~40%.⁵

The visible effect on a numerical workload is mostly cache behavior. Halving slot sizes means each cache line holds twice as many tagged values, and arrays of objects (rare in stdlib's hot loops, common around them) become half as cache-cold. Pointer compression also constrains what the compiler can do—for instance, every dereference now requires a base+offset compute—but the cache wins generally outweigh the new instruction.

Mutable heap numbers (V8, 2025)

A subtler 2025 addition: in-place updates of HeapNumbers in script-context slots. Previously, a script-level let seed = ...; seed = next(seed); pattern would allocate a fresh HeapNumber on each reassignment, even when the optimizer could prove only a single number was being threaded through. Now the slot can own its HeapNumber and mutate the underlying double in place. The case study in the post is Math.random's state. For numerical code that uses module-scoped accumulators or threaded random-number-generator state, this eliminates a previously-invisible per-update allocation.

Hidden classes and inline caches

Every V8 object points to a hidden class that records what properties it has, in what order, at what offsets, and with what attributes. The naming is genuinely a mess, and it isn't your fault if you've been tripped up by it. One concept, and every engine picked a different word for it:

Engine	Calls them
V8	`Map` — nothing to do with the JavaScript `Map` builtin
SpiderMonkey	Shape — widely borrowed, so you'll meet it outside Firefox
JavaScriptCore	Structure
Chakra	Type

Hidden class is the fifth name, and the one this post uses.⁶ Academic papers use it—but so does V8, constantly, in its own documentation, whenever it's explaining rather than implementing. The heap doc introduces Maps as "also known as hidden classes or shapes" and heads the defining section "The Map (Hidden Class)"; V8's docs page on the subject is titled Maps (Hidden Classes) in V8. It isn't the obscure choice—it's the one term that travels across all four engines and back into V8's own prose.

Two objects with the same hidden class are bit-compatible to V8's fast paths. Hidden classes are built incrementally: each added property transitions the object to a new one, which is why { x, y } and { y, x } end up different despite having the same property names.

If you come to this from C or C++, Benedikt Meurer's talk on types, classes, and maps offers the translation that tends to land hardest: a V8 hidden class plays roughly the role of a vtable pointer plus a field-offset table. "Keep the hidden class stable" then reads as the same discipline: don't reshape a struct at runtime.

Inline caches (ICs) are per-call-site memoizations of the hidden classes the site has seen. The hot path replaces dictionary lookups with a hidden-class check plus a load from a known offset. As long as a site only sees one hidden class (monomorphic) it stays fast. With two to four it becomes polymorphic—a chain of compare-and-load attempts. Past that threshold V8 gives up and falls back to a generic dictionary lookup (megamorphic), and the hot-loop assumption is over.

Hidden-class stability buys more than a fast IC, though. As Vyacheslav Egorov works through in What's up with monomorphism?, a monomorphic site lets the optimizer treat repeated hidden-class checks as redundant and eliminate all but the first. A polymorphic site structurally cannot get that: each variant needs its own guard.

ValidityCells are the trick that lets prototype-based code stay fast. Each prototype's hidden class carries a single-bit "still valid?" flag; ICs that depend on a clean prototype chain can collapse all their lookup checks down to a read of that bit. A mutation anywhere on a prototype chain (including, catastrophically, on Object.prototype) flips the cell, invalidating every IC that depended on it.

Anything that participates in a hot dispatch path has to be shape-stable—argument-shape validators, factory functions for option objects, anything that builds an object on the way into the kernel. The cost of polymorphism is not an extra cycle per access; it is the loss of the entire optimizer's bet on this call site.

Elements kinds

For array objects, V8 tracks a separate tag called the elements kind that describes what's in the numerically-indexed slots. Plain Array instances live on a six-cell lattice: PACKED_SMI / PACKED_DOUBLE / PACKED_ELEMENTS, plus the three HOLEY_* variants. The lattice is one-way. An array can be demoted from PACKED_SMI to PACKED_DOUBLE (by a single float write) to PACKED_ELEMENTS (by a single string or object write), or to a HOLEY_* variant (by delete, by new Array(n) without immediate fill, by writing past length). On the value-type axis the demotion is permanent for the life of that array, even if the offending value is removed—writing an integer back over the float doesn't restore PACKED_SMI. The holey axis is the one exception: Array.prototype.fill can return a holey array to packed, including one made holey by delete.⁷

Typed arrays—Float64Array, Int32Array, and friends—sit outside this lattice on their own elements kinds (FLOAT64_ELEMENTS, INT32_ELEMENTS, etc.). They cannot be demoted, cannot be made holey, and cannot have their type changed—the typed-array API enforces all three. From V8's point of view, a typed-array element is already in its raw machine-level representation on the backing buffer; reading one is a memory load, not a wrapper unwrap.

Typed arrays aren't an optimization; they're a guarantee. Every element is provably a fixed-width number, every access has a well-defined in-bounds outcome, every stored value is provably the right type.

That guarantee, rather than raw speed, is why numerical stdlib code is built on them—and the distinction matters, because the obvious version of the claim isn't true. A plain Array of integers isn't automatically slower than an Int32Array. Typed arrays even do work a plain array doesn't: every write is coerced to the element type, so 2**31 stored into an Int32Array reads back as -2147483648, and 300 stored into a Uint8ClampedArray reads back as 255.

What they buy isn't a lower floor. It's a narrower band. A plain array is fast right up until something demotes it, and then it's quietly slower for the rest of its life—and nothing in the code says so. A typed array can't be demoted, so the millionth call performs like the first. That's what write it like C is asking for; the Zen says "prefer predictable performance," not peak performance.

And one reason has nothing to do with the optimizer at all: a typed array is a view over an ArrayBuffer, which is the layout a C routine expects on the other side of a native add-on, so the data crosses without being copied.

What this means for stdlib-style code

This is where the aphorisms cash out. Each convention below protects one specific decision the machinery above makes, and once you can name the decision, the convention stops reading as a prohibition.

One dtype, one implementation. stdlib ships separate dasum and sasum—double-precision and single-precision absolute-sum kernels—instead of one polymorphic kernel that dispatches on argument type. Two stories combine here, elements kinds and ICs: passing a Float64Array and a Float32Array to the same function makes its loop body see two different elements kinds, so the IC at the indexed-access site goes polymorphic, and the optimizer's bet gets weaker on every successive call. Two separate functions, each used only with its own dtype, stay monomorphic. stdlib makes this argument in its own source, too. @stdlib/array/base/arraylike2object exists to normalize array-likes into one fixed-shape descriptor object, and its README says why in as many words: if objects are built with properties in different orders, "then those objects will have different 'hidden' classes," and a function fed enough of those shapes "will cause the function to be considered 'megamorphic'." The workaround is a helper whose only job is to hand every call site the same shape.

One of stdlib's maintainers frames the whole discipline in terms of the language it's imitating: "Just like in C you have to create every single different typed interface as a new function, we're doing the exact same thing." The proliferation of near-identical kernels isn't duplication that a cleverer abstraction would collapse. It's the point.

Hidden classes have to be stable up to and across the kernel. When a kernel takes an options object—a strided-ndarray descriptor, a BLAS-style transposition flag—every call site has to build that object the same way, with the same property names in the same order. If a caller mutates the object after construction (adds a property, deletes one), it transitions the hidden class out of whatever the kernel's IC was specialized on. stdlib's convention follows from that: every property defined at construction time, in a fixed order, never mutated afterward—and, where it matters, that construction centralized in a factory rather than left to each call site to remember.

Typed arrays do double duty. They give you (1) shape stability—Float64Array cannot become a Float32Array, cannot acquire holes, cannot become megamorphic—and (2) unboxed representation—every element is a raw double on the backing buffer, no HeapNumber wrapper. A plain Array of numbers can have the second: a PACKED_DOUBLE array stores raw doubles in a FixedDoubleArray, no wrappers. What it can't have is the first—and losing the first costs you the second. One string write demotes the array to PACKED_ELEMENTS, and every element becomes a tagged pointer again. The guarantee is what makes the representation durable.

Loops stay lean. TurboFan can optimize an enormous amount, but it cannot prove invariants the source doesn't make available to it. This is the mechanical content of be explicit—the optimizer is one of the readers whose mental model won't match yours. Three patterns follow from it:

Loop unswitching. Where a loop body branches on a value that doesn't change inside the loop (an option === 'conjugate-transpose' flag, say), stdlib hoists the branch out and writes two loop bodies. TurboFan has loop-invariant code motion, but it can't always prove an opaque comparison is side-effect-free, so the fix lands at authoring time instead—as a stdlib maintainer puts it, "if you need to duplicate loops, so be it." (In benchmarks it does a second job: it keeps the optimizer from eliminating the unobserved branch and silently measuring less work than you meant to.)
Scalar decomposition before entry. Where a complex scalar alpha is used throughout a loop, it gets decomposed once before entry—const re = real(alpha); const im = imag(alpha);—and the loop reads re and im. Even where TurboFan would have hoisted the calls, being explicit removes the uncertainty.
No allocation inside the loop. Calling .get(i) on a Complex128Array inside a loop allocates a complex-number object every iteration, so kernels cast to a Float64Array view of the same memory with @stdlib/strided/base/reinterpret-complex128 and read pairs of doubles instead. It's the same memory layout a C implementation would walk with a double* over interleaved real and imaginary parts, which is the part of write it like C that's literal rather than analogical. Athan Reines' accessor-protocol post unpacks that two-layer arrangement: logical complex-values on top, raw floats underneath.

The through-line: move anything invariant across iterations out of the loop at authoring time, rather than leaving it for the compiler to maybe hoist.

Plain arrays stay packed. Where a plain Array is unavoidable—the stdlib generic dtype, argument lists—stdlib builds it with a literal [ ] or with push rather than new Array(n) followed by index assignment, and removes indices with splice rather than delete. Once an array transitions to HOLEY_*, every read pays for a possible prototype-chain walk in case Array.prototype[i] was set. That cost is what fix them early is pointing at: on the value-type axis the lattice is one-way, so there's no later cleanup pass that undoes it, and even on the recoverable holey axis the fix has to be deliberate—fill is something you have to know to reach for, not something that happens on its own.

Prototypes don't change after instances exist. Adding a method to a constructor's prototype after instances exist invalidates every IC that watched that prototype. Adding anything to Object.prototype invalidates every prototype-walking IC in the running program. This is mistakes are infectious with a runtime mechanism behind it—one upstream mutation is paid for by every downstream caller, none of whom did anything wrong.

Verify, don't theorize. This was the part I found most reassuring, because it means none of the above has to be taken on faith. Run Node.js with --allow-natives-syntax and use %HaveSameMap(a, b) to confirm two objects share a hidden class, or %DebugPrint(arr) to read off an array's elements kind. Run with --trace-opt --trace-deopt to watch promotions and deopts scroll past, with the reason attached—wrong map is the one you'll see most, and it's worth knowing that's the string V8 prints for a hidden-class mismatch. IC state transitions are a little more work: the old --trace-ic flag no longer exists, and its replacement --log-ic writes to a file rather than to your terminal—V8's own tools/ic-processor then reads that file. For the generated machine code, --print-opt-code dumps it. For the IR, --trace-turbo plus Turbolizer.⁸ The decisions that matter for a hot path are observable, which means "is this really monomorphic?" is a question you can answer rather than argue about.

Benchmark hygiene. Microbenchmarks that look reasonable can measure nothing—Egorov's Performance Through the Spyglass is the canonical demonstration, and his one-line version of it is hard to improve on: optimizers eat microbenchmarks for dinner. The optimizer is allowed to constant-propagate, dead-code-eliminate, hoist invariants out of the timing loop, and unroll. stdlib's benchmark convention defends against this by including explicit lightweight assertions—e.g., a NaN self-inequality check (if ( x !== x ) { b.fail(...) }) inside and after the timing loop. The trick exploits NaN's inequality with itself: the check is false for any ordinary value, so the fail path never runs. But the compiler still has to observe the read of x (which defeats dead-code elimination) and it can't fold the check away.

Where this seems to be heading

The rules—monomorphic call sites, stable hidden classes, typed-array storage, lean loops—have held for a decade. The infrastructure underneath has been rebuilt three or four times and presumably will be again. I'm not going to pretend to know what V8 ships next, but three things look like they're already in motion:

Float16 and Float16Array arrived in browsers recently. The numerical case for half precision is mostly machine-learning-shaped (model weights, intermediate activations) but that case will increasingly intersect numerical-JS code living next to ML pipelines. stdlib has already moved: float16 is a working dtype with a real Float16Array behind it, and it participates in the promotion and safe-cast tables like any other. complex32 is the genuinely forward-looking one—it's named in @stdlib/ndarray/dtypes and in the dtype-kind taxonomy, but no Complex32Array exists yet to back it and its addition is slated as future work.
The Maglev → Turboshaft path keeps compressing the warmup curve. A hot loop reaches optimized machine code earlier on each successive V8 release, and where parts of a call graph used to sit in Ignition, never quite crossing the TurboFan threshold, they now land in Maglev instead. That makes occasional-path code matter slightly more than it used to: polymorphism in a moderately-called function is now something the optimizer has to account for, where before it wasn't looking.
Mutable heap numbers and similar fine-grained representation tricks are the genre of optimization V8 is shipping right now. These are mostly invisible from the source (good code keeps getting faster) but they reward the same disciplines that are already best practice: fewer abstraction layers between the source's intent and a single number in a single register.

Most of this is invisible if the kernels are well-behaved. That's by design. The optimizer's job is to take code that describes a numerical loop dynamically and execute it as if it were a statically-typed one. The shorter the gap between those two, the easier its job.

Which is where I ended up on the aphorisms. Write it like C isn't nostalgia for a language most of stdlib's JavaScript never touches, and don't be clever isn't a general plea for humility. They both describe the shape a speculative optimizer is looking for, written in the imperative because that's the form a convention takes. Fifteen years of compiler engineering went into recognizing that shape at runtime. The list is short because the shape is simple—which is also, I think, what simple is beautiful is doing at the end of the Zen of stdlib.

Acknowledgments

This work was supported in part by the National Science Foundation under Award No. 2449410.

Disclaimer: Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.

V8's Ignition announcement gives both figures: baseline-compiled machine code was occupying roughly a third of Chrome's JavaScript heap, and Ignition's bytecode is 25–50% the size of the equivalent baseline machine code. ↩
The launch post puts Crankshaft at "more than ten thousand lines of code per chip architecture," against a few thousand for TurboFan's architecture-specific layer. ↩
Both ratios are the V8 team's own: Maglev compiles roughly an order of magnitude faster than TurboFan and an order of magnitude slower than Sparkplug. ↩
The Turboshaft write-up reports compile time "divided by 2" versus the sea-of-nodes pipeline. ↩
The ~40% heap-memory reduction is reported in V8's pointer-compression write-up. ↩
The engine-by-engine mapping is Mathias Bynens and Benedikt Meurer's, from JavaScript engine fundamentals: Shapes and Inline Caches (14 June 2018). Their list adds the collision warnings the table compresses away: Hidden Classes is confusing with respect to JavaScript classes, Maps with respect to JavaScript Maps, and Types with respect to typeof. ↩
V8's elements-kinds post carries an inline amendment, "Update @ 2025-02-28: There is now an exception to this for Array.prototype.fill specifically," and gives no further detail. Testing on Node v24.19.0 puts the exception slightly wider than the note implies: fill restores packed status from delete-induced holes as well. ↩
Singh's NodeBook has flag tables—informational, behavioral, and how to pass them—which are a far better starting point than the raw --v8-options dump. ↩

Your AI Policy Doesn't Have to Apply to You

Mara Averick — Wed, 12 Aug 2026 14:06:03 +0000

A confession: stdlib doesn't have an AI-use policy.

It isn't for lack of trying. There's an open RFC proposing guidance on AI usage—citations to prior art, disclosure requirements, a carve-out for "good first issue"¹—and a draft PR with the policy text, both of which are from December 2025.² Both are still open. Both are still drafts.

It's not because AI usage is hypothetical here, either. We've had stdlib core contributors participating in METR's randomized trial on AI's effect on experienced open-source developers since 2025. Philipp Burckhardt, one of stdlib's co-maintainers, wrote up his experience on the project blog, including which tools he uses and how his workflow changed.³ More recently, Karan Anand described using the codebase itself as the prompt.

So: we use these tools, we've said so in public, and (beyond some check boxes in our PR template) we still haven't codified what we expect from anyone else. We've gotten stuck, and one of the sticking points has been an obvious one—discomfort with publishing a rule we're not going to hold ourselves to.

This is a real objection. It's also, I've come to think, the wrong one, and we're not the only project stalling out on it. The question isn't whether AI is being used on this project. It's whether there's anything written down that a contributor can read.

Plenty of projects got past this. Melissa Weber Mendonça keeps a running catalog of what's been published;⁴ Kate Holterhoff's RedMonk survey was up to eighty-six policies as of April 2026, dimensionalized by stance and primary concern;⁵ CHAOSS's AI-alignment working group runs a companion list with an incident-and-discussion layer.⁶

Given the scope of the discourse around AI usage in open source, this is a strikingly small corpus—and a young one.⁷ Nobody is late to a settled consensus here. As James Fredley put it, after a tier-by-tier read from the primary documents: "there is no single industry-wide standard yet."⁸

What the policies themselves agree on is narrower than it first looks. Stance splits three ways—permissive, ban, undecided—and the stated concerns split at least three ways again: code quality, licensing liability, and ethics. Where they do line up is on something small and specific: contributors are responsible for understanding what they submit. Sean McLellan's case for the Assisted-by: Git trailer states the reasoning plainly—using Co-authored-by: claims shared authorship, and with it accountability. A tool can't hold up its end of that bargain.⁹ The trailer itself is one lightweight implementation; the claim underneath it is what travels.

Accountability is what the trailer is for; responsibility is what the policies actually ask of you. Part of that is legal clarity—the human is the sole author of the commit, whatever helped them write it. But what responsibility looks like in practice depends on the author's relationship to the project.

Two mechanisms tend to get bundled together here. Disclosure is a record-keeping rule—the Assisted-by: trailer, the AI-assistance section of our own PR template—and what it produces is provenance: what helped write this. Everyone takes part in that one. Gating is a permission rule: who may use these tools, on what, with how much latitude. What follows is an argument about the gate, not the disclosure.

A maintainer who merges a bad change is still there in three months when it breaks. They wrote the module it broke, or reviewed it, and they will be the one bisecting at midnight to find out why the build went red. Responsibility, for them, isn't a claim. It's a structural fact about where they're standing.

An infrequent contributor who submits a bad change usually isn't there. Not out of bad faith—that's simply what infrequent means. Whatever I take responsibility for this means when they sign off on their PR, it can't mean quite the same thing as it does for a maintainer. The position it's said from is different.

So a policy that says you're responsible for what you submit is asking two structurally different things of two structurally different people, while looking like it asks one thing of everyone. That's roughly where our hypocrisy objection came from. It's also, it turns out, where the objection comes apart.

The word for it

There's a word for a rule that behaves this way, and I'm going to use it even though it's unfamiliar, because the precise word does work the familiar ones don't.

A rule can be defeasible: correct as a default, and properly overridden when the situations it applies to genuinely differ. The everyday version is the speed limit is 45, except for the ambulance. The rule holds. The exception is principled. The exception doesn't retroactively invalidate the rule.¹⁰

The open-source policy version goes something like this:

There's a naïve consistency heuristic: don't require of others what you wouldn't do yourself. It's correct for most governance choices. Don't require signed commits if you don't sign yours. Don't require test coverage your codebase doesn't have.

But it's defeasible where the situations genuinely differ, and AI-use policy is the clean case. A maintainer using AI owns the fallout, holds the project's mental model, and can recognize when the output is wrong. A first-time contributor using AI may be offloading understanding to the tool—producing work they can't fully vouch for—and has no accountability chain yet. Those are different situations. Different rules are warranted.

The distinction comes down to what's underneath the rule. Because I own the fallout in a way you don't is principled. Because I said so isn't. The trust ledger is what makes the difference legible, and it's why "just be consistent" is worse advice than it sounds.

The naïve-consistency rule is itself defeasible. That's the whole thing. It's a good default, it does honest work most of the time, and this is one of the situations where the exception is warranted rather than merely convenient.

Ghostty's AI_POLICY.md lays out the usual disclosure-and-human-in-the-loop rules for contributions, and then closes with this:¹¹

These rules apply only to outside contributions to Ghostty.
Maintainers are exempt from these rules and may use AI tools at their discretion; they've proven themselves trustworthy to apply good judgment.

Two sentences. The first says this policy is for you, the contributor, not for me. The second says why. And the why isn't brash authority—it's a claim about accumulated context. They've proven themselves. You can agree with it, or push back on it, or ask what the proving consisted of.

So: you (potential contributor) can weigh and evaluate the claim. Naming the asymmetry on the page—rather than writing a symmetric-sounding rule and then quietly not applying it to yourself—is the move. It's two sentences. It's been shipped, in public. Just like a good CONTRIBUTING.md, the honest accounting is a kindness.

"You're just formalizing hierarchy"

There's a critique here I too feel the pull of, and it might be part of what keeps projects like ours from making the move. You're building a hierarchy where maintainers get one rule and contributors get another.

The hierarchy is already there, and has been the whole time—and it's not just maintainers vs. contributors, there are often tiers of trust (maintainers is just a useful shorthand). A maintainer with three years of context on a codebase reads a stranger's PR differently from how they read their own or one of a long-time contributor. The maintainer/reviewer knows what's load-bearing, what's under active refactor, which review objections are terminal versus fixable. None of that is malicious; most of it isn't even conscious. It's what accumulated context does. Call it a "trust ledger" (a term I'll return to in a subsequent post).

What a written policy does is convert an existing asymmetry from invisible-and-unchallengeable into visible-and-contestable. That's an accountability gain, not a hierarchy invention. Writing it down is what makes it something you can be held to.

If you've been sitting on a policy because the but-I-don't-hold-myself-to-this objection kept stopping you: note it, acknowledge that it does ethical work worth respecting in most contexts, and it doesn't apply here in the way it feels like it does. The situations genuinely differ. Different rules are principled when the difference has a reason you can be held to.

I'm not saying every project should ship one; whether it's right for a given project depends on more than fits in a piece this size. What I am saying is that this particular reason for stalling—the hypocrisy-avoidance reason, the one that stopped us—is dissolvable.

Take it, if it's useful. Ours has been open since December; I'm hoping this is a step towards closing it out.

Mara Averick is a developer advocate at Quansight and contributor experience lead for stdlib.

Acknowledgments

This work was supported in part by the National Science Foundation under Award No. 2449410.

Disclaimer: Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.

stdlib-js/stdlib issue #9347, "[RFC]: Add guidance concerning AI usage"—proposing disclosure of AI assistance in pull requests and issues, excluding good first issue work from AI-assisted resolution (per the draft PR's rule 5: "these issues are intended to help newcomers learn about the project and gain experience with the mechanics of contributing"), and ruling out model output posted as comments on GitHub or Zulip. Opened December 24, 2025. ↩
stdlib-js/stdlib pull request #9459—the companion draft PR adding the policy text, opened December 31, 2025; still a draft as of this writing. ↩
Philipp Burckhardt, "Using AI in the development of stdlib," Numerical Bits, July 17, 2025—a reflection on stdlib's participation in METR's "Impact of Early-2025 AI on Experienced Open-Source Developer Productivity" study, in which two stdlib core contributors worked randomized project issues under AI-allowed and AI-disallowed conditions—a snapshot from early 2025; both the models and the surrounding tooling have changed considerably since. ↩
Melissa Weber Mendonça, open-source-ai-contribution-policies—a community-sourced catalog framed simply as "a list of policies by different open source projects about how to engage with AI-generated contributions." Roughly 100 project rows as of August 2026, plus separate sections for ongoing discussions and adjacent references. ↩
Kate Holterhoff, "The Generative AI Policy Landscape in Open Source," RedMonk, February 26, 2026 (with rolling edits through April 12, 2026). The dimensionalized cross-section—stance, primary concern, disclosure requirement, adoption date—of the same underlying corpus Melissa's catalog and CHAOSS's list track from different registers. Companion visualization site. ↩
CHAOSS AI Alignment Working Group, "Awesome LLM Policy," live PR-editable catalog with a nine-part taxonomy—including discussion threads and incident evidence as first-class categories alongside finished policy artifacts. ↩
The adjacent body of work is about as short as the list of trackers. Sviatoslav Sydorenko's EuroPython 2026 reference gist collects the maintainer-side tooling and files both Holterhoff's RedMonk piece and the CHAOSS list under "Surveys of the policy landscape"; the three trackers each reference the other two. ↩
James Fredley, "Assisted-by: How open source projects are drawing the line on AI contributions," All Things Open, May 11, 2026. A tier-by-tier read from the primary documents—QEMU, Gentoo, and NetBSD at the total-ban end; LLVM, Fedora, the Linux Kernel, Apache, OpenInfra, OpenTelemetry, and Rocky Linux across the permissive-with-disclosure middle—arguing that Assisted-by: is settling in as the de facto convention over Co-authored-by:, which "implies legal personhood." Fredley is chair of the Apache Grails PMC. ↩
Sean McLellan, "Assisted-by git trailer: provenance for AI-assisted commits," Barista Labs, June 20, 2026. Key line: "Co-authorship says this entity shares authorship and accountability." Pulled into stdlib's own trailer discussion by Athan Reines' (comment on issue #9347)—not necessarily the line's original point of entry into OSS AI-policy discourse, just where this piece's thread of it traces back to. ↩
The term has a longer life outside software. H. L. A. Hart, "The Ascription of Responsibility and Rights," Proceedings of the Aristotelian Society, New Series 49 (1948–1949): 171–194, is the canonical statement of the legal version—rules that hold unless a specific exception overrides them. John L. Pollock, "Defeasible Reasoning," Cognitive Science 11, no. 4 (1987): 481–518, formalizes the everyday version: how people reason with rough-and-ready rules that new information can defeat, and what it takes for an override to count. ↩
Ghostty, AI_POLICY.md (fetched 2026-08-03). Iterated in public via PR #8289 (initial disclosure rules, August 2025) and PR #10412 (hardened into the standalone policy, January 2026). ↩

Do you WANT contributors?

Mara Averick — Thu, 23 Jul 2026 16:12:00 +0000

My open-source origin story goes something like this: I fixed a typo, tweeted some stuff, tripped, fell, and found myself in the inner circle of a large-scale OSS ecosystem with an active, supportive community! It's trite but true—neither universal nor unique. But "inner circle of a large-scale OSS ecosystem" is where I landed, and it's colored a lot of what I've written since—including an implicit assumption that you (person who is reading this) are trying to build an ecosystem-scale project too.

POSE (Pathways to Enable Open-Source Ecosystems) has it right there in the name. It expressly describes this shape as the first item in the list of activities it's meant to support:

Building and maintaining a distributed community of external contributors who will actively participate in the ongoing development of the open-source product.

However, this isn't the only (or even the most common) experience for open-source maintainers or projects. Most projects run on one to three active maintainers.¹ Solo isn't a failure mode; it's the default.

There's a wide spectrum of how folks define open source: from "it's just a license" to "radically open and participatory." For the rest of this post to land, I need you to accept the license-end as at least legitimate—not right, necessarily, just legitimate. There's no need to re-litigate the decades-long disagreement in order to say that you, as a maintainer, get to decide the bounds of participation in your project.

An open-source project's first few artifacts are click-through: license (checkbox), README (template), .gitignore (whatever your framework spits out). Then you hit CONTRIBUTING.md—the first artifact that actually asks you what you want. Sure, there are best practices and helpful guides for you to follow, but it's where your project starts having opinions instead of defaults. So it's worth pausing and really unpacking what you want yours to look like. It's more than the mechanics of filing issues and submitting pull requests: CONTRIBUTING.md is the foundational framework for the relationship between your project and the unnamed masses who may or may not encounter it.

In fairness, the bare-bones version of contributor guidelines may work just fine for you. Or you and your project may have a version that was working in the past, but no longer feels sufficient.

For years, I had a Venn diagram I used in talks to illustrate what I called the "FOSS happy place":

It wasn't a lie—it reflected my early experience as a contributor to open source (even if my contributions weren't code-shaped). It's still not "wrong," per se. But it is guilty of radical oversimplification—not quite discretizing a continuous variable, but definitely improper dimensionality reduction. Critical features, like time, remuneration, and changing conditions/priorities are nowhere to be seen.

I'm not the only one whose journey was typo fix → full-time job/way of life. Kent C. Dodds (among the best in the game of open-source developer experience, in my opinion) describes a similar origin story in How getting into Open Source has been awesome for me (2020). I mention him for two reasons, and neither is throwing him under the bus: one, it's not just me; two, it's not dev-rel delusion—because (unlike me) he's a lines-of-code, PR-reviews, engineer-shaped maintainer of a widely used open-source project (Testing Library).

A career in open source isn't always a heart-eyes-emoji experience. Evan Czaplicki gave a great (aptly named) talk at Strange Loop 2018: The Hard Parts of Open Source. The challenges he describes seem somewhat inherent to the craft: you can't please everyone, conflicts will arise, things that once motivated you will be deeply draining at times. Anyone who's struggled through a group project in school will recognize the shape. None of that friction is new—LLMs didn't create maintainer burnout. In a 2019 piece by Nadia Eghbal, "The rise of few-maintainer projects", she wrote:

The salient issue for maintainers today is less about growing contributor numbers and more about navigating the flow of developers who are clamoring for their time.

Sounds familiar, right? AI has ratcheted things up. Maintainers are seriously rethinking what their relationship to their projects and users looks like. And here's where I return to CONTRIBUTING.md because this is a place where you get to be explicit about the choices you're making. Even if nobody reads every word (and most people don't read CONTRIBUTING files at all), writing one is how you set your boundaries in the first place. A CONTRIBUTING.md that reads:

No thanks! I'm gonna go it alone.
But feel free to fork and do whatever you like!

may not be what you're used to seeing (in fairness, that sentiment is likely carried through the absence of a CONTRIBUTING file), but it's legitimate. Or, maybe you think it isn't. Maybe it's anathema to open source, BUT it is a move that someone could make.

Am I recommending it? No. But I'm not you. I'm not everyone. And, importantly, it forces you to acknowledge that you get to set your boundaries and expectations. Again, this is an oversimplification. If you're maintaining a mature project with a set governance pattern and change-management process, waking up and burning your contributing process to the ground is likely to have serious fallout. But, that doesn't mean that you can't experiment (especially if the status quo feels like you're headed off a cliff.)

Certain projects have, by design, made the bar for contribution high for legitimate reasons. Debian's already the perfect example of a working gatekeeping mechanism that's high-demand. You need a sponsor, you find a mentor, you meet in person with someone who can vouch for you—as Nadia Eghbal put it, "Debian's process is built on the need for trust."²

But Debian is one shape among several. Athan Reines pitched a taxonomy for this: not "how open is your project" on a slider, but "what shape of project are you actually running?" He described four archetypes: the walled castle, the clique, the university, and the hippie commune.

The walled castle (or black box). You get the code, but the drawbridge stays up. SQLite is the cleanest live example. Their copyright page has a section literally titled "Open-Source, not Open-Contribution," which says:

SQLite is open-source, meaning that you can make as many copies of it as you want and do whatever you want with those copies, without limitation. But SQLite is not open-contribution...the project does not accept patches from random people on the internet.

You can't misread that. It's on their homepage. This archetype fits when the maintainer has a firm boundary they don't want to soften—a totally legitimate choice. It also fits when there's an author who's just done. The question: Do you want contributors? The answer: No.

The clique. You need to know the right people to get the secret password. OpenBSD is the best not-pejoratively-clique example I could find. Their hackathons page says, plainly: "Hackathon attendees come by invitation only. Some new people in the community who show promise are sometimes invited to see if they have what it takes." Linux kernel subsystems run on the same social logic at scale: the kernel docs describe a "chain of trust" where pull requests from unknown developers are received warily by subsystem maintainers until they've earned their way in. This archetype fits when the cost of misplaced trust is high and the mechanism for establishing trust is "does someone I already trust vouch for you."

The university. If you do your homework and score high enough on your exams, we'll admit you. Debian's process, above, is the archetypal case: the sponsor and mentor are part of a longer sequence that includes an application manager, a Philosophy & Procedures exam, a Tasks & Skills exam, and then DAM approval (or not). Their own docs are unusually honest about the deal: "the whole NM process is very strict and thorough. This is not meant to discourage people... but it does explain why the New Member process takes so much time." Kubernetes runs the most numerically explicit ladder I've seen: Member (sponsored by two reviewers from different companies), Reviewer (primary on 5+ PRs, reviewed 20+ substantial ones), Approver (30+ merged, nominated by a subproject owner). If you want the stdlib-adjacent case, pyOpenSci has documented onboarding flows for reviewers and editors: guest-editor probation, editor-in-chief nominations, a peer-review process modeled on academic journals. This archetype fits infrastructure that's load-bearing enough that mistakes are expensive to unwind, and it works if the syllabus is real. (It fails, badly, if the syllabus is a rebrand of "vibes-based homework we won't tell you the rules of.")

The hippie commune. Do you have a pulse? Yes? You're in. freeCodeCamp basically checks for a pulse and hands you a first timers only label. Their whole cultural stance is "let us help you land your first PR." I've been part of projects like this, and it's actually onerous in its own way. But, they're where a lot of folks get started. Without these, the rest of the spectrum loses its future contributors and maintainers. MDN Web Docs runs the same posture on the docs side: their contributing guide is basically "there's a place for you here, even if your grammar isn't perfect." (Wikipedia is the mother of this archetype but isn't code-shaped, so treat that as a cultural reference, not a technical one.) This archetype fits projects where the marginal contribution has low blast radius, and the real bottleneck is reach or discoverability, not integration cost. It also fits projects whose goal is teaching people to contribute, where the code is almost a byproduct of the mentorship.

In reality, there is, of course, a spectrum—and shades of gray as well. A project doesn't necessarily have to operate in a single mode, either. SQLite runs some clique-shaped review practices under its walled-castle surface. Debian's university process has real clique-shaped social realities inside it. Any given project can occupy more than one archetype at once—a codebase that's walled-castle at the core and hippie commune at the docs layer, say. And most projects drift between shapes as they age.

I also want to be clear that you're ALLOWED TO MOVE where your project is at. Is hippie-commune mode failing you in the age of AI slop? Maybe you run an experiment with a more rigorous onboarding (or have folks who have already contributed to the project mentor newcomers through their first PR so that the onus doesn't always fall on the maintainer.)

There is no more a platonic form for a perfect CONTRIBUTING.md than there is for a universally "perfect" job. The fit is between your project and its contributors. What works for one can be exactly wrong for another.

But here's why the taxonomy belongs in a piece about what you actually want: it forces you to say the thing out loud. "I want a hippie commune" is a different maintainer future than "I want a university," and both are different from "I want to keep the code out here but the process in here." You can't dodge the question by writing a CONTRIBUTING.md that just describes issue templates. The people who read it (the ~7 who will) can tell which archetype you're aiming for even when you haven't named it. Might as well spell it out.

There are pros and cons to the types of friction you introduce—selectively inviting who can interact, permanently banning a suspected peddler of AI slop, toggling off the "Issues" section of a repository. But, if the relationship (that between a maintainer and contributors) is evolving in such a way that it feels like it cannot hold, that's its own type of failure. Neither the maintainer nor "the community" are to blame when things end in a silent resignation or a public crashout—but maybe they can be avoided by experimenting with things you hadn't previously considered as being "worth it."

Like my old FOSS-happy-place Venn diagram, the chart below doesn't capture the n-dimensional reality of working in open source. But I'd like to think it's an improvement. On the x-axis you have maintainer/project (dis)comfort. And the y-axis is something akin to ROI (return on investment)—demand from contributors/community/ecosystem.

The catch is that you don't really know where an experiment lands on this chart until you try it—not how much it'll cost you (the x-axis), and not what you'll get back (the y-axis). That doesn't mean you have to try everything. But it's worth paying attention to where things actually fall, rather than where you assumed they would.

Here are some things that we're trying (or considering taking for a spin):

Code review as the alignment step. Ed Yang makes the case that code review is where humans do the alignment work now. As AI takes on more of the implementation, the reviewer's job shifts away from line-by-line mechanics and toward the big-picture questions—does this fit, should it exist, is this the shape we want?
Using AI as a market-research companion, not a PR-generation machine. Instead of AI writes the pull request, it's AI helps you see the landscape. Feed it the parallel projects—for us that's NumPy, SciPy, Math.js, and friends—let it aggregate the patterns everyone else has converged on, and then you decide what fits. Same tool, pointed at what should we build instead of let's crank out code.
Livestreamed PR review. Twitch, Discord, YouTube—pick your poison. Someone watches a maintainer work through a review in real time. The discomfort scales hard depending on who you are (some folks would genuinely rather chew glass than do their job on camera), but it puts other humans in the room at the moment you're deciding something. And it teaches in both directions: people watching learn what makes a good contribution and what being a maintainer actually takes. It's knowledge capture without the curation—which means it might surface insights you never knew people wanted.

None of this is guaranteed to work. Most of what gets written about open-source communities and contributor experience gets written after the fact—after something worked. That means there's a bottom drawer somewhere full of the things people tried that didn't (those posts mostly don't get written.) And even the experiments that did work worked in the specific conditions of that project—its size, its maintainers, its users, its moment. Different projects, different fits. This isn't Wills and Trusts. You can iterate. Your CONTRIBUTING.md can change. Your governance can change. Your mind can change. Whatever you want to do is okay—just own it. And if you're trying something (the thing that's working, or the thing that isn't) come tell us about it. We're figuring it out too.

Sources

Mara Averick is a developer advocate at Quansight and contributor experience lead for stdlib.

Acknowledgments

This work was supported in part by the National Science Foundation under Award No. 2449410.

Disclaimer: Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.

Linux Foundation, OpenSSF, and Harvard LISH. Census III of Free and Open Source Software. December 2024. https://www.linuxfoundation.org/hubfs/LF%20Research/lfr_censusiii_120424a.pdf?hsLang=en; GitHub. Octoverse 2025. https://github.blog/news-insights/octoverse/octoverse-a-new-developer-joins-github-every-second-as-ai-leads-typescript-to-1/. ↩
Nadia Eghbal. "The Rise of Few-Maintainer Projects." Increment, 2019. https://increment.com/open-source/the-rise-of-few-maintainer-projects/. ↩

DEV Community: Mara Averick

Write It Like C: What V8's Optimizing Compilers Explain About the Zen of stdlib

A note on vocabulary

Why a numerical JavaScript lens?

A 15-year ladder

Crankshaft (2010–2017)

Ignition + TurboFan (2016–2017)

Sparkplug (2021)

Maglev (2023)

Turboshaft (2023–2025), not an execution tier

Putting the ladder back together

The representation primitives that make this work

SMI vs. HeapNumber

Pointer compression (V8 8.0, 2019)

Mutable heap numbers (V8, 2025)

Hidden classes and inline caches

Elements kinds

What this means for stdlib-style code

Where this seems to be heading

Further reading

V8 team primary sources

Talks and write-ups by V8 team members and adjacent practitioners

stdlib and stdlib-adjacent

Acknowledgments

Your AI Policy Doesn't Have to Apply to You

The word for it

"You're just formalizing hierarchy"

Acknowledgments

Do you WANT contributors?

Sources

Acknowledgments