English for Unison Language Developers

Unison breaks enough conventional assumptions — no text files, no manual dependency versions, code identified by its hash — that discussions about it often need a sentence of setup before the actual question, just to establish which unfamiliar concept is in play.

Key Vocabulary

Content-addressed code — Unison’s model where each function definition is identified by a hash of its own syntax tree, not by a name in a file, so renaming a function never breaks anything that calls it. “We renamed this function across the whole codebase without touching a single caller — nothing actually depends on the name, only the hash.”

Codebase manager (UCM) — the tool that replaces both the file system and the build tool for Unison code, storing definitions directly and providing commands to browse, edit, and test them. “There’s no git diff to review here in the usual sense — we walk through the change inside the codebase manager, which shows exactly which hashes changed.”

Ability — Unison’s typed mechanism for describing an effect a function can perform, like network access or exceptions, similar in spirit to an effect system, checked at compile time. “The compiler rejected this function because it performs a network call but wasn’t declared with the Network ability — that’s not boilerplate, it’s a real missing declaration.”

Term / definition — the fundamental unit of Unison code, a single named value or function stored by its hash, the building block everything else — namespaces, dependencies — is composed from. “Instead of thinking in files, think in terms — each function is its own independently stored, independently hashed definition.”

Distributed computation — Unison’s ability to send a serialized function, by its content hash, to run on a remote node without needing that node to already have matching source code deployed. “We didn’t need to deploy new code to the worker nodes at all — we shipped the computation itself, by hash, and the worker fetched and ran it directly.”

Common Phrases

• “Is this actually a rename, or did the definition’s logic change too — since that would give it a different hash?”
• “Are we browsing this change in the codebase manager, or trying to diff it like a normal file?”
• “Does this function need to declare the Network (or IO) ability, or is that a real effect it’s missing?”
• “Is this one term, or are we accidentally describing several definitions bundled together?”
• “Are we shipping code to the worker, or just shipping the computation and letting it fetch by hash?”

Example Sentences

Explaining a refactor’s safety in review: “This is a pure rename in Unison — the hash is identical, so every existing caller is guaranteed to keep working without a redeploy.”

Describing an ability error: “The build failed because this function calls into IO without declaring the ability — that’s the type system catching an undeclared side effect.”

Justifying a distributed design: “We’re not managing deployed versions on each worker — we send the function by hash, and the worker executes whatever it receives.”

Professional Tips

• Explain content-addressed code early when onboarding someone — most confusion about “how do renames not break things” traces back to not knowing hashes, not names, are the real identity.
• Point people to the codebase manager instead of a text editor when they ask “where’s the file” — there usually isn’t one in the traditional sense.
• Treat an ability compile error as a legitimate missing declaration, not a formality — it usually means an undeclared side effect really exists.
• When describing distributed features, be precise about distributed computation by hash versus a conventional deploy — they solve different problems and confusing them undersells the design.

Practice Exercise

1. Explain why renaming a function in Unison never breaks its callers.
2. Describe what an ability is and why a missing one causes a compile error.
3. Write a sentence explaining how Unison ships computation to a remote worker.

Navigating Nuance: Common Pitfalls for Non-Native Developers

The core concepts of Unison – content-addressed code, abilities, and a distributed approach – are powerfully expressed in English. However, translating technical ideas into fluent professional communication can be surprisingly tricky, even for experienced developers. Many non-native speakers face challenges not just with the individual words but with the way those words are used within a collaborative development environment. It’s easy to fall into patterns that sound awkward or don’t convey the intended meaning precisely. Let’s look at some common areas where adjustments can make a significant difference, particularly when discussing code changes and design decisions.

One frequent issue is over-reliance on literal translations. Directly converting phrases like “code storage” into “хранилище кода” (which translates to “repository of code”) might sound stilted in an English discussion. Instead, developers naturally use terms like “storage,” “data location,” or simply referring to the content being stored – “the content-addressed data.” Similarly, when explaining an ability, a phrase like “functionality” can feel overly formal. Describing it as “what the ability does” is often clearer and more accessible. Another area of concern is verb tense usage. While the past tense is frequently used for completed tasks (“I refactored the module”), the present perfect (“I have implemented this feature”) can sometimes sound too assertive, particularly when proposing a change. Using “I’ve added” or “I’m working on” conveys a more collaborative and tentative approach.

Furthermore, phrasing around potential problems – bugs, errors, or unexpected behavior – needs careful consideration. Simply stating “there is an error” is often too blunt. Framing the issue as “we observed an unexpected result” or “we encountered a situation where…” allows for a more constructive discussion about root causes and solutions. A good example of this can be seen in PR descriptions: instead of saying “Fixed bug,” consider “Resolved an issue with incorrect data serialization, preventing crashes under specific conditions.” This level of detail demonstrates thoroughness and understanding.

Finally, remember that concise language is key. Developers value clear communication; avoiding overly complex sentence structures will always be appreciated. Focus on conveying the essential information efficiently.

# Example: Unison Content Lookup - Finding a file by its hash

unison lookup --hash <file_hash>

This command, executed in the Unison CLI, demonstrates a core function – locating code based on its cryptographic hash, a fundamental concept underpinning content-addressed storage. It’s a practical illustration of how developers discuss and utilize these concepts daily.