[Dev-iL]

The problem: a contributor, person or AI agent, can't learn from the repository why Hamilton's foundations are built as they are: why a function's name is its node, or why integrations autoload. The reasoning sits in old commits, pull requests on two GitHub homes and mailing-list threads, or nowhere, so a change can reopen a settled question.

What changes: eight decision records, writeups/adr/2611-02 to 2611-09, with their index rows (listed below). Each carries the status Reconstructed from codebase, which writeups/adr/README.md adds: written after the fact, from the code and its history, for a decision the code already embodies, claiming no acceptance of the record itself. Each quotes and links what the pull requests and threads where its decision was made record, and says where they record nothing. CONTEXT.md links the function-modifier record, and CONTRIBUTING.md points at the records.

Where this sits: split out of #1806 at the review's request into three stacked pull requests, one commit each:

1. Add a glossary, and fix the contributing and developer setup guides #1808, the glossary and documentation fixes;
2. this pull request, commit bef7e00f;
3. Add scripts/verify, a command that runs the checks CI runs, one recipe per area #1806, scripts/verify.

They merge bottom-up, each rebased onto main after the one below lands; until #1808 lands, GitHub shows its commit here too.

Shown working, at bef7e00 (the two scripts are described below):

• uv run prek run --all-files --hook-stage pre-merge-commit: passes, license headers included.
• python3 urlcheck.py writeups/adr/2611-0[2-9]-*.md: 249 URLs, 0 failed.
• python3 linkcheck.py . bef7e00f: 11 Markdown files, 18 relative links checked, 0 problems.
• No workflow runs here: it touches no path in any workflow's pull_request filter.

Decisions (no decision record is reopened; reasons are folded below): the author's calls are the status Reconstructed from codebase, reading the pull requests where each decision was made, and three stacked pull requests; sources are linked by stable URL, and what a discussion says is attributed and linked.

Debt left:

• The permalinks pin commits on main, nearly all ef88b1e, and nothing flags a record whose code later changes.
• Some reasoning was never recorded and stays marked so, such as 2611-03's phase order.
• PostHog code outside the core library, named in 2611-09, has no settled place under its policy.

Before and after (an illustrative example). Task: make Hamilton load its integrations lazily.

• Before: you read hamilton/registry.py, see every extension imported up front, and propose a lazy mode, not knowing one was built and dropped in added environment variable to disable extensions autoload #1095, or why opt-in loading was rejected there.
• After: 2611-05 gives the decision, the lazy and opt-in alternatives with their reasons and links, and what changing the default would break.

The eight records

• 2611-02: functions define nodes;
• 2611-03: function modifiers resolve in a fixed lifecycle;
• 2611-04: deprecations follow a warn/fail version contract;
• 2611-05: integrations load through an autoloaded registry;
• 2611-06: data I/O goes through registered loaders and savers;
• 2611-07: lifecycle adapters replace graph adapters;
• 2611-08: packages ship as apache-hamilton*, with sf-hamilton* redirects;
• 2611-09: released artifacts don't phone home.

How they were written, and how the checks work

The records were written from the code at main (ef88b1e), the commits, the pull requests that carried them (on stitchfix/hamilton for those from before the move in February 2023, whose numbers did not carry over), their issues, and the dev@ and general@ threads. What those discussions record about rationale, alternatives, who decided and consequences is quoted, attributed and linked. Where they record nothing, the record says so. Every source is linked by a stable URL: pull requests and issues by full URL, commits by full SHA, and file:line citations as permalinks at ef88b1e, except one historical citation at e00f144.

urlcheck.py and linkcheck.py are short scripts of mine, kept outside the repository:

• urlcheck.py fetches every URL in the files it is given. Pull requests, issues, commits and their comment and review anchors go through the GitHub API, along with the line each permalink names; mailing-list threads through the archive's API, which fails for an unknown thread; other pages over HTTP.
• linkcheck.py <repo> <commit> checks that every relative link in the Markdown files the commit changes resolves in that commit's tree, and that those files mention no glossary, record or harness file the tree lacks.

Decisions, with their reasons

• Author's call: the status Reconstructed from codebase, rather than Proposed, which the review asked for, or Accepted (retroactive; …), as first proposed in Add scripts/verify, a command that runs the checks CI runs, one recipe per area #1806.
• Author's call: read the pull requests where each decision was made, and record what they offer.
• Author's call: split Add scripts/verify, a command that runs the checks CI runs, one recipe per area #1806 into three stacked pull requests, one commit each.
• Sources are linked by stable URL, which the review asked for; GitHub does not link a bare apache/hamilton#N inside a repository file.
• What a discussion says is attributed and linked to where it was said, rather than presented as the project's reasoning.

What the pull requests, issues and threads added, record by record

• 2611-02, functions define nodes.
  • The 2020 README's reasoning for one implementation per name, and for the _ prefix.
  • The dates each later rule arrived.
  • That a duplicate name inside one module silently replaces the first.
  • The tag-based dependencies and node redefinition that were proposed and turned down.
• 2611-03, the function-modifier lifecycle.
  • The pull request that carried it, Implements opinionated decorator lifecycle stitchfix/hamilton#28, where both people called it mostly a refactor of 2019 behavior.
  • Stacking order as one motive.
  • The dynamic-resolver phase, added in 2023.
  • That insensitivity to order is an aim with open issues (Clarify behavior of decorator ordering #57, Use @inject with @pipe decorators #748).
  • The augment decorator dropped in review.
• 2611-04, deprecations.
  • Full parametrized decorator stitchfix/hamilton#163, and that removal at 2.0 was already the practice before the decorator.
  • Where the migration guide and the pre-release rule came from.
  • The 0.x exemption.
  • The frozen clocks Make pipe, dynamic_transform and model keep their deprecation schedule, and warn with FutureWarning #1804 found.
  • The warning categories it weighed.
• 2611-05, the extension registry.
  • Introduces *_extensions to extend functionality in hamilton stitchfix/hamilton#273, and the pandas-bound decorators it fixed.
  • The circular import a reviewer caught.
  • The import-time report (Slow import of hamilton's Builder #1059) behind added environment variable to disable extensions autoload #1095.
  • The lazy mode added environment variable to disable extensions autoload #1095 built and dropped.
  • The pydantic breakage greedy loading caused.
• 2611-06, data adapters.
  • Materialization #236 merged to a feature branch and reached main through dynamic task spawning + grouped execution #220.
  • The "three limitations" framing dates from 2024.
  • Why adapters must be dataclasses (Documentation for adapters #150).
  • Why Any loaders come last (Supports "Any" in loader types #536).
  • Construction-time materializers, listed as not chosen in 2023, were adopted in 2024.
• 2611-07, lifecycle adapters.
  • The decision was made in Lifecycle customization #592, and Lifecycle Customization Umbrella Issue #605 is its tracker.
  • The announced aim, and why there are two layers.
  • The cost of one implementation per method, which caching hit.
  • The graph-adapter deprecation that never happened.
• 2611-08, apache-hamilton.
  • The name was forced by a binding −1 on the 1.89.0 release vote, citing the Incubator's distribution guide.
  • The sub-packages were renamed in Update package names and builds #1488.
  • The redirects came in Bump apache-hamilton version to 1.90.0 #1539 and Add redirect packages, fix tests, and prep for sub-package release #1588, built with setuptools on purpose.
  • The drift the record first described was fixed by Build the sf-hamilton* redirect packages from their sources' extras and Python floor, and drop a stale Python version from the docs #1805.
  • The ASF move's aims, from the incubation proposal.
• 2611-09, no telemetry.
  • Who approved Remove usage telemetry (PostHog) from Hamilton #1512.
  • The release vote that shipped it.
  • That the stub first shipped in 1.90.0.
  • The UI import error it caused (Hamilton local ui fails with ImportError #1649).
  • More PostHog code outside the core.

[Dev-iL]

@skrawcz @elijahbenizzy @zilto Please see the ADRs, and especially the sections where "reasoning could not be recovered fully". If you remember why these things are the way they are, I'd be happy to replace what the AI figured out with your testimony.