English for Automerge Developers

Automerge treats application data like a JSON document with full CRDT-based merge guarantees and history tracking, so conversations about it mix data-modeling vocabulary with the same conflict-free replication concepts common across the local-first ecosystem.

Key Vocabulary

Document — an Automerge data structure representing the entire state of an application (or part of it) as a JSON-like object, with every change tracked and mergeable, rather than a single mutable blob overwritten on each save. “We’re not just overwriting a JSON blob on save — the document tracks every individual change, which is exactly what lets two offline edits merge automatically later.”

Change / changeset — an individual, atomic modification to a document, recorded with enough metadata (author, timestamp, causal history) to be merged deterministically with changes made concurrently elsewhere. “Each edit is captured as its own change, so when two people were offline and both edited the title, Automerge can merge both changesets instead of one silently overwriting the other.”

History / time travel — the ability to inspect or reconstruct any prior state of a document by replaying its recorded changes, since nothing is destructively overwritten. “We can actually recover this — nothing was destructively overwritten, so we can use the document’s history to time-travel back to the state before the bad edit.”

Merge — the deterministic process of combining two divergent copies of a document (each with changes the other hasn’t seen) into a single consistent result, without manual conflict resolution in most cases. “Both branches diverged while offline, but the merge resolves automatically since Automerge’s CRDT guarantees give us a consistent result without a manual conflict step.”

Actor ID — a unique identifier assigned to each device or session making changes to a document, used internally to establish a deterministic ordering when merging concurrent changes. “Every change is tagged with an actor ID, which is part of how Automerge decides deterministic ordering when two changes touch the same field at the same time.”

Common Phrases

• “Is this document tracking individual changes, or are we still just overwriting the whole blob on save?”
• “Can we recover this using the document’s history, or was that data actually lost?”
• “Does this merge automatically, or does this particular data shape need custom conflict handling?”
• “Are we tagging changes with a consistent actor ID across devices, or could that be causing the ordering issue?”

Example Sentences

Explaining the model to a new engineer: “Every edit becomes its own recorded change here, not just an overwrite — that’s what makes it possible to merge two people’s offline edits without losing either one.”

Discussing a recovery scenario: “We don’t need a separate backup system for this — the document’s history already lets us reconstruct any prior state before the accidental deletion.”

Reviewing a data model: “This nested structure might not merge cleanly under concurrent edits — let’s check whether this needs a more CRDT-friendly shape before we commit to it.”

Professional Tips

• Emphasize that a document in Automerge isn’t just JSON storage — it’s change-tracked JSON, and that distinction is central to explaining why offline merging works at all.
• Use change granularity to debug merge surprises — inspecting the actual recorded changes is far more productive than guessing at what “should” have happened.
• Highlight history as a built-in undo and audit trail, since teams often don’t realize they get this capability for free with a CRDT-based document model.
• Flag data shapes early in design review that might merge poorly under concurrent edits — some structures (like ambiguous array reorderings) need deliberate design to merge cleanly.

Practice Exercise

1. Explain to a teammate why change-tracked documents allow offline edits to merge automatically.
2. Describe how document history could be used to recover from an accidental bad edit without a separate backup.
3. Write a sentence flagging a data structure in a design review that might not merge cleanly under concurrent edits.

Navigating Nuance: Addressing Feedback Beyond Literal Translation

As an Automerge developer – particularly if you’re learning professional English – it’s easy to focus on directly translating terms from your native language. While understanding the concept of “local-first CRDTs” is crucial, effective communication relies heavily on how those concepts are expressed within a collaborative development workflow. It’s not just about saying “conflict”; it’s about explaining why a conflict occurred and proposing a solution in a way that resonates with your team. Many non-native speakers find the subtleties of phrasing – particularly around potential disruption, changes, and rollback strategies – incredibly challenging. Recognizing these nuances is key to building trust and ensuring smooth collaboration.

One common area where misunderstandings arise is when discussing edits made offline. Imagine receiving a comment on a pull request describing a change in a document history merge: “This merge introduced inconsistencies. The previous version’s data structure is now corrupted.” This statement, while technically accurate, can feel incredibly alarming to someone unfamiliar with the underlying CRDT mechanics. A more approachable phrasing might be, “I noticed some differences in how this section was edited offline. We’ve implemented a mechanism that handles these types of divergent changes automatically – it’s designed to minimize disruption and ensure data integrity.” The key is shifting from describing a problem (corruption) to explaining the solution (automatic handling). Similarly, when requesting a review, saying “Please check this PR” feels incredibly vague. Instead, consider “Could you please review this PR focusing on potential conflicts arising from offline edits and ensure the document history remains consistent?”

Another frequently encountered situation involves describing changes to the Automerge configuration itself – particularly around merge strategies. Explaining why a particular strategy was chosen can be tricky. Saying something like “We’re using a ‘merge-first’ strategy” isn’t enough; you need to articulate why that strategy is preferable in this context, perhaps mentioning its impact on offline synchronization or conflict resolution speed. Focusing on the outcome – “We’ve opted for a ‘merge-first’ strategy to prioritize minimizing disruption during offline edits and ensure rapid synchronization when connectivity returns” - demonstrates a deeper understanding of the system’s operation.

Finally, remember that Slack conversations often require concise yet clear explanations. A quick message like “Fix conflict” isn’t sufficient; it begs the question: what conflict? A more productive response might be, “Resolved conflict related to offline edits – implemented a delta merge strategy as per the team’s agreed-upon protocol.”

Here’s an example of how you might use git mergetool to initiate a manual merge with specific options when dealing with a complex conflict:

git mergetool --strategy=recursive --no-prompt /path/to/merge_tool

This command invokes the merge tool, specifying the recursive strategy (which is often suitable for CRDTs) and disabling automatic prompting, allowing you to manually resolve conflicts as they arise. The --no-prompt flag ensures that the merge tool doesn’t interrupt your workflow with unnecessary questions.