Lore

A timeline-oriented narrative of how this codebase came to be. Dates are derived from git commit timestamps and tag dates.

Eras

The Cadence prehistory (Oct 2016 – Oct 2019)

The repository's first commit is dated 2016-10-24 with the message "The new beginning". For its first three years the project lived as uber/cadence, the orchestration backend developed at Uber. Many of the early architectural choices that survive today — sharded History service, gossip-based membership via Ringpop, append-only history events, separation between Frontend / History / Matching — were established in this era.

The fork (Oct–Nov 2019)

In late October 2019 the repository was renamed: commit "Renaming of package uber/cadence to temporalio/temporal (#4)" lands on 2019-10-26, followed by "Move client package dependency to go.temporal.io/temporal (#6)" on 2019-10-30 and "Update to use new temporal-proto. (#12)" on 2019-11-13. This sequence marks the formal split between Cadence and Temporal. References to Cadence still appear in the comment history (e.g. PR titles like "Cherry pick #3627 from Cadence") for several years afterward.

Steady growth (2020–2022)

Annual commit volume grows from ~950/year in 2020 to ~995/year in 2022. The major themes of this era are:

• Persistence layer rework — the common/persistence/ package gains the SQL implementations (MySQL, Postgres, SQLite), making Cassandra one of several supported backends rather than the only one.
• Visibility on Elasticsearch — the indexed visibility store moves out of the primary database.
• Search Attributes — typed indexed metadata on workflow executions.
• Worker versioning v1/v2 — early attempts at letting workers declare which versions of code they can run.

The Nexus and CHASM era (2023–2026)

graph LR
    classic[Classic workflow engine<br/>2016–2022] --> hsm[HSM<br/>state-machine library<br/>~2023]
    hsm --> chasm[CHASM<br/>state-machine framework<br/>~2024]
    chasm --> generalised[Workflow / Scheduler /<br/>NexusOperation as<br/>CHASM Libraries]
    classic --> nexus[Nexus<br/>2024]

This is the era the repository is currently in. Annual commit volume jumps from ~1,000 to ~1,300/year starting in 2024. Two large, connected efforts dominate the codebase:

• Nexus — Temporal's framework for cross-namespace and cross-cluster service composition. Source: common/nexus/, components/nexusoperations/, chasm/lib/nexusoperation/. The architectural notes in docs/architecture/nexus.md are extensive.

• CHASM — generalised state-machine runtime in chasm/. Workflow itself (the original engine) is being re-expressed as a CHASM Library. Recent churn is dominated by chasm/lib (571 commits in the last 90 days, second only to service/history).

The chasm/lib directory holds the libraries that have already migrated:

Library	What it is
chasm/lib/workflow/	Workflow as a CHASM Library
chasm/lib/scheduler/	Scheduled-workflow engine
chasm/lib/nexusoperation/	Nexus operation state machines
chasm/lib/callback/	External callback delivery
chasm/lib/activity/	Standalone activity (no parent workflow)

Longest-standing features

A handful of subsystems trace back to the Cadence days and have weathered every refactor:

• History sharding via RangeID — the fence number that lets a new shard owner reject stale writes from the previous owner. The pattern survives unchanged.
• Transactional outbox between History and Matching — Transfer Tasks have always been the bridge from "history wrote an event" to "Matching has a task ready to deliver". Implementation has moved between files, but the contract has not changed.
• Ringpop membership — gossip-based shard ownership has been there since day one. The library has been forked into temporalio/ringpop-go but the protocol is identical.
• Append-only History Events — event sourcing as the source of truth for workflow state. Mutable State has been added on top, but never replaced events.

Major rewrites

• Cadence → Temporal package rename (Oct–Nov 2019) — the largest single reorganisation, captured by PR #4.
• NDC / multi-cluster replication overhaul (~2020–2022) — the service/history/ndc/ and service/history/replication/ trees were rewritten to support N-cluster replication with conflict resolution.
• Visibility decoupling — moving visibility into its own pluggable store (common/persistence/visibility/) rather than living in the primary DB.
• Worker Versioning rewrites (v1 → v2 → v3) — three iterations of how workers declare compatible code versions. The most recent (versioning_3_test.go is the largest test file in the repo) is still being stabilised.
• State machines for callbacks and Nexus — first via the bespoke HSM library at service/history/hsm/, then generalised to CHASM at chasm/.
• Fairness in Matching — the priority/fairness scheduling system in service/matching/ (with extensive design notes at service/matching/fairness.md) replaced an older FIFO-only scheduler.

Deprecated features

• --services= flag — the old comma-separated form on temporal-server start was deprecated in favour of repeated --service= flags. The deprecation is still warned about in cmd/server/main.go.
• Pre-CHASM HSM root — early callbacks used a workflow-rooted HSM tree; CHASM superseded this. The HSM library survives as the in-process state machine engine for one specific shard.
• Old Cadence references — package names, comments, and the occasional cherry-pick PR title. Not actively maintained but kept for context.
• --root and --config-dir flags on the server — marked deprecated in favour of --config-file. See cmd/server/main.go.

Growth trajectory

xychart-beta horizontal
    title "Commits per year (1,500-commit scale)"
    x-axis ["2016", "2017", "2018", "2019", "2020", "2021", "2022", "2023", "2024", "2025", "2026"]
    y-axis "Commits" 0 --> 1500
    bar [34, 343, 501, 954, 954, 838, 995, 1019, 1306, 1290, 727]

The codebase has grown from a single contributor's "new beginning" in late 2016 to a project with 326 unique committer addresses, sustaining over a thousand commits per year for the last three full years. Year-over-year contributor velocity has been highest during the Nexus/CHASM era, reflecting the ongoing investment in the next-generation execution engine.