In a recent post, I argued that a real release is a declaration—a line in the sand that says, this is the version we stand behind. A declaration begs a follow‑up: what exactly are we declaring? The honest answer is: requirements. A release without requirements is just a pile of diffs; a release grounded in requirements is a promise we can audit, test, and keep.
This is where classic software requirements work—yes, the unglamorous kind—earns its keep in data and analytics. If releases create accountability, requirements make that accountability usable.
What a release declares
Every release declares three things, whether we say them out loud or not:
- What the system now does (capabilities and rules).
- How well it does it (quality attributes like performance, usability, security, reliability).
- Under what constraints (policies, interfaces, data contracts, privacy limits).
Karl Wiegers and Joy Beatty’s Software Requirements (3rd ed., Microsoft Press) (one of my favorite software books, and I’ve now been moved to write a review, wait for it to get posted on this blog) gives us a simple, durable scaffolding for these declarations: levels and types of requirements (business, user, and functional), plus the nonfunctional “beyond functionality” qualities that shape how a system behaves. Their table of contents alone shows the shape of the discipline: levels and types; quality attributes; baselines and version control; and the “links in the requirements chain” we call traceability.
Releases that don’t name these pieces force teams and stakeholders to infer them from code and dashboards. That’s how silent semantic drift happens.
Why releases imply requirements
A release is the social moment when we stop treating changes as experiments and start treating them as obligations. Obligations need text.
- Reliability demands measurability. If we say latency will be “better,” nobody knows when to escalate. If we state “95% of reports render in ≤3s at district scale,” we’ve written a quality requirement that can be tested and defended. Wiegers & Beatty dedicate an entire part of the book to specifying quality attributes precisely for this reason.
- Governance demands provenance. When oversight asks, “Who approved redefining chronic absenteeism?” provenance isn’t a Git link—it’s the trace from objective → user need → requirement → design/test → release note. The book’s “Links in the requirements chain” makes that connective tissue explicit, including traceability matrices and motivations for tracing.
- Planning demands boundaries. Release planning is hard when “scope” is a mood. Requirements create a baseline—an agreed set of statements we can deliver, change‑control, or defer. Requirements baselines and version control are first‑class citizens in the text, and they map cleanly to versioning semantics (major/minor/patch).
Strong, usable requirements make versioning meaningful
Version numbers are promises about compatibility and blast radius. Requirements make those promises legible:
- Major versions: The requirement set intentionally breaks a contract. In data terms, we might retire
attendance_rate_v1in favor of a new definition that excludes excused absences, with a mapped migration path. That’s a requirement change at the user and functional levels (different question answered), and at the quality attribute level (freshness/performance envelopes might change). The book’s treatment of “levels and types of requirements” and “beyond functionality” gives us the vocabulary to say this crisply. - Minor versions: Additive features that don’t break existing consumers. Requirements here describe new use cases or reports without changing the meaning of existing ones.
- Patches: Defect corrections that do not alter the declared meaning or quality envelopes of the system.
Without requirements, these labels blur. With them, versioning becomes a public service.
Traceability is the skeleton of a trustworthy release
For analytics and ML, traceability isn’t bureaucracy—it’s navigation. When you can trace a requirement forward to tests, code, model features, and dashboards, and backward to business objectives and stakeholder needs, you can answer two critical release questions in seconds:
- What must we retest if we change this?
- Why does this behavior exist at all?
Wiegers & Beatty’s “Links in the requirements chain” section covers both the practice and the artifacts (like the traceability matrix) used to maintain those links. In our domain, that means connecting metric definitions to queries, model cards to datasets and fairness tests, and API schemas to published data contracts.
Requirements quality is release quality
The book’s early chapters and “Good practices” theme emphasize that requirements need to be understandable to their audience, testable, consistent with each other, prioritized, and feasible. Those aren’t academic niceties; they’re the difference between a version you can stand behind and a version that generates 40 “why did this number change?” emails. The table of contents calls out both the foundations (“The essential software requirement”) and the management practices that keep them healthy.
In data/AI terms, “usable” requirements look like this:
- Precise metric semantics. Not “chronic absenteeism improved,” but “students with ≥10% missed instructional days in the past 90 days, excluding documented medical leave.” That’s a functional requirement tied to an explicit definition—and to the business objective it supports.
- Quality attributes for analytics. Freshness (“≤60 minutes end‑to‑end latency”), stability (“no schema changes within a minor version”), reproducibility (“queries return identical results when run against the same snapshot”), and fairness (“equal opportunity difference within ±2% across named subgroups on the held‑out set”). These are quality requirements; the book treats this domain broadly under “Beyond functionality.”
- Constraints that matter. FERPA boundaries, PII handling rules, and policy‑driven retention limits aren’t “assumptions”; they’re constraints. Naming them gives release planning a real wall to work with. The book situates constraints alongside quality attributes for exactly this reason.
Baselines are how we say “this is the release”
A requirements baseline is simply the set of requirements we’ve committed to for a release. Changes after the baseline aren’t sneaky; they’re governed—assessed for impact, prioritized, and either included or deferred. In the Microsoft Press edition, “Requirements management practices” covers baselines, version control, status tracking, and change control—exactly the muscles we flex when a release is near and risk is high.
This is liberating, not constraining. A baseline doesn’t slow teams; it removes ambient uncertainty. Product owners know what to communicate. Engineers know what to test. Data stewards know what to document. Leaders know what to promise.
Releases, requirements, and the data/ML stack
A few places where the software requirements lens tightens up our analytics and ML work:
- Data products and APIs. Treat schemas and data contracts as requirements with compatibility promises. Breaking fields and renaming categorical values are major changes; adding nullable fields is minor. Every change is anchored to a requirement ID and appears in release notes with rationale and trace back to stakeholder needs. The “requirements version control” and “change happens” sections connect directly to this operational rhythm.
- Models as requirement-bearing artifacts. Model cards routinely state objectives, training windows, and thresholds. Make them requirements, not narratives: the classification threshold, acceptable drift budgets, subgroup performance floors, and retraining triggers are quality requirements tied to tests. They are then traceable through evaluation scripts to release gates—exactly the “links in the chain” idea.
- Dashboards as versioned stories. A dashboard is not “live content”; it’s the public face of a requirement set. When the story changes because the definitions change, that’s a major version with a migration note, not a Tuesday tweak.
The governance dividend
Governance isn’t a committee; it’s clarity on what changed, why it changed, and who approved it. Strong requirements make that clarity cheap:
- Audits become lookups. With baselined requirements, a release audit is a quick trace: business objective → requirement → tests → release artifact. The book’s sections on change control (including entry/exit criteria and impact analysis) model this flow.
- Risk concentrates where it belongs. Instead of rubber‑stamping every pull request, reviewers focus on release gates—where requirement changes are baselined or rejected. That’s a better use of expert time and a cleaner governance record.
The reliability dividend
Uptime matters; semantic stability matters more. Requirements make both possible:
- Test coverage means requirement coverage. If you can’t map a test to a requirement, you don’t know what your test suite protects. If you can’t map code to a requirement, you might have orphan behavior. Wiegers has written at length about using traceability to prevent both. The 3rd‑edition chapter on links in the chain puts those practices in one place.
- Rollbacks that actually roll back. When the requirement set is versioned, rollback isn’t “revert a commit and hope”; it’s “return to the last baselined requirement set and its corresponding artifacts.”
Bringing it back to releases
Our stance at edudatasci.net is simple: declare deliberately. Releases are the moment when rapid iteration becomes institutional memory. Requirements—expressed at the right levels, with the right qualities, and managed with baselines and traceability—are how we make those declarations credible.
If you want releases that hold up under pressure—public scrutiny, policy review, a scary midnight page—invest first in the thing that releases imply: strong, usable requirements. The field‑tested guidance in Software Requirements (3rd ed.) remains one of the most pragmatic roadmaps for doing exactly that, including how to articulate levels/types, specify quality attributes, establish baselines, and connect the links in your requirements chain.
That’s how you turn a version tag into a promise—and a promise into trust.
