A new version is not merely “whatever is latest.” It is an identifiable set of changes that people can explain, verify, compare, and, where possible, reverse.
Websites change content, apps fix defects, factories alter materials, and services revise procedures. Without knowing which version was used, why it changed, or what happened afterward, teams attribute outcomes to unreliable recollections. Versioning preserves a baseline and a decision history; it does not require every service to use Git. Semantic Versioning provides useful rules for software with a defined public API [R01], while GitHub documents describe releases, notes, and associated artifacts [R02]. Neither replaces change management for physical or human operations.
1. Separate version, revision, iteration, release, and deployment
| Concept | What it identifies | Example |
|---|---|---|
| Version | Recognizable state of a solution | Booking system V1.2 with revised rules |
| Revision | A change or review within a history | Revision of confirmation wording |
| Iteration | Cycle of learning and adjustment | Test flow, observe, improve, retest |
| Release | A version made available to defined recipients | V1.2 delivered to three restaurants |
| Deployment | Technical installation or activation | Publishing files to a server |
| Update | Change applied to an existing system or process | Replacing reception instructions |
Terms vary by organization. What matters is what was actually available to whom. Merging on GitHub does not prove that the server received a version; successful deployment does not prove that users could complete tasks. An editorial revision is not necessarily a public release.
2. Define “version” for the type of solution
In software, a version may include a code tag, package, configuration, and data schema. For websites, it includes templates, content, routes, and assets. For physical products, it may include design drawings, bill of materials, manufacturing instructions, and production batch. Changing a component without changing code still matters. For services, it may mean controlled revisions of procedures, training, hours, and support.
Hybrid systems have coexisting versions: app V2, hardware revision B, support procedure edition 3. Record compatibility and dependencies. A UI update may require training or changed service commitments.
3. Establish a baseline you can reconstruct
A baseline is the reference against which future changes are assessed. Record ID, date, scope, requirements, relevant files or documents, resources, configuration, owners, and test evidence. Detail should be proportional to risk.
For a small service, a dated operating procedure with assigned roles and delivery conditions may be sufficient. In software, include repository commit, release artifacts, configuration, and necessary migrations. Do not include credentials or personal data in release notes. Reference secured systems instead.
If the previous state cannot be reconstructed, do not promise easy rollback. Changes to data, materials, and processes may have consequences that cannot be undone by replacing files.
4. Classify and connect changes to reasons
Distinguish corrective changes (repair), adaptive changes (different environment), evolutionary changes (new capacity), and experimental changes (test a hypothesis under defined conditions). A release can combine several types, but their purposes should remain clear.
Each change should answer: Which observation or requirement prompted it? Which version is affected? What component changed? What behavior is expected? What test will verify it? What risk is introduced? Who approved it? This creates the chain hypothesis → decision → change → version → test → finding → next decision.
Not every change is an experiment. Correcting a typo may be maintenance. An SEO change measured over time can be exploratory, but it is not necessarily a causally controlled experiment.
When a change originates in an issue or request, relate the version to the prioritized findings and decisions log. This preserves why the change was made and what was deliberately excluded.
5. Choose numbering that fits; do not force SemVer everywhere
For software with a public API, Semantic Versioning 2.0.0 uses MAJOR.MINOR.PATCH: MAJOR for incompatible API changes, MINOR for backward-compatible functionality, PATCH for backward-compatible bug fixes [R01]. It does not generally mean “big visual redesign / medium change / small fix” for every website. Without a defined compatibility contract, the number alone says little about breakage.
A small organization might use v1, v2, and a date, provided identifiers are unique and recorded. A physical batch might use model A / revision C / batch 004; a service procedure might use SOP-bookings-v3. Avoid names such as final-really-final-2.
6. Plan release strategies and exposure limits
A version may be delivered to a small group, one area, a production line, or the full market. Gradual rollout allows problems to be observed before exposure grows, but requires monitoring and a way to stop the change. UK government's beta guidance describes initial private access followed by broader release as evidence and support improve [R03]. This illustrates a principle, not a universal phase requirement.
Specify recipients, eligibility, actual activation time, prior version, training, communications, monitoring, support, stop conditions, and response owner. Where changes affect contracts, data, or safety, research applicable obligations before rollout.
Do not label code on a branch “published” or a successful build “validated.” Distinguish prepared, integrated, deployed, accessible, and verified in use.
7. Manage compatibility, migrations, and rollback
For software, document compatibility with earlier clients, data, dependencies, and APIs. Database migrations may require verified backups, restore procedures, and a plan for new records written after migration. Rolling back code does not automatically restore data to its prior state.
Physical products may require identifying units by batch or recalling parts; reversal may involve logistics and communication. For services, returning to a prior procedure means staff must know which instructions are current and must not use conflicting versions.
Before release, ask: Can we reverse it? What cannot be undone? What triggers stopping the change? Who owns the response? If rollback is impossible or unsafe, prepare alternative mitigation and correction plans.
Before expanding delivery or attempting a rollback, review solution tests and regression checks. A version change can fix the visible case and break related behavior.
8. Compare versions without automatically claiming causality
If retention increases, complaints fall, or SEO visibility rises after a version, timing alone does not prove that version caused the change. Seasonality, other channels, customer mix, competitors, and measurement changes may all matter. Preserve original hypotheses and document simultaneous changes.
Where feasible, compare equivalent periods and groups, use suitable controls, and avoid changing too many factors together. When causality cannot be established, report observed association with limitations, not demonstrated success of one modification.
To decide which hypothesis to revisit after each delivery, use the Design–Test Loop, which distinguishes evidence-based iteration from repeating changes until a metric looks favorable. An orderly version history does not itself establish causality.
9. Record and communicate the release
Useful release notes state the version and actual date, recipients, visible changes, important internal changes, incompatibilities, known risks, user actions, completed tests, and support contact. They need not reproduce every technical commit, but should explain changes affecting users. GitHub releases can group code versions with tags, notes, and artifacts [R02].
Keep a decision log to explain why the solution changed, a test register for what was verified, and a version history for what was delivered. They are related, but not interchangeable.
Worked example: three website versions and an SEO service
A fictional agency delivers a website and then provides monthly content and SEO work:
| Version | Hypothesis or reason | Controlled change | Available evidence | Provisional decision |
|---|---|---|---|---|
| Web V1 | Establish a presence and measurement baseline | Initial structure and content | Starting query and event records | Retain baseline |
| Web V2 | Improve match to specific search needs | Reorganize selected page content | Query and click changes over a defined period | Investigate before assigning cause |
| Web V3 | Improve discovery of related articles | Add documented contextual links | Navigation and visibility with external factors | Retain or adjust based on evidence |
Every result is hypothetical. The team records the URL, version, actual publication date, changes, baseline, other active campaigns, and comparison limitations. Improved rankings after the update are not sufficient to prove that internal linking caused the outcome.
The website is the digital product. SEO is the recurring service that changes product versions. Confusing them can produce promises that the service does not control. Similar patterns apply to recipe iterations or app updates.
Common mistakes and limitations
Treating commit, merge, and publication as identical; losing configuration version history; making changes without a baseline; using SemVer without a defined API; promising rollback while ignoring data and consequences; releasing tests without support; comparing incompatible results; concealing contractual changes; deleting unfavorable history; claiming causality from timing.
Versioning is useful because another person can reconstruct what changed, what was available, what was verified, and why the next decision followed.
What you should have when finished
A version and change log with identifier, scope, actual date, owners, linked requirements and findings, tests, delivery evidence, recipients, compatibility, risks, decisions, and correction mechanism. It need not be complicated, but it must be continuous and truthful about what is known.
References
- [R01] Tom Preston-Werner. Semantic Versioning 2.0.0. https://semver.org/
- [R02] GitHub Docs. Managing releases in a repository. https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository
- [R03] UK Government Digital Service. How the beta phase works. https://www.gov.uk/service-manual/agile-delivery/how-the-beta-phase-works