Enterprise AI Project Wiki · Environments, versions, and release
Version number
Also calledSoftware version number · Version identifier · Release version
A version number is an identifier assigned under an agreed rule to a particular state of a changing object so that the state can be distinguished, referenced, ordered, or related to other states. A useful project version number resolves to a defined object and change record. If the same number can point to different content, or a changed number cannot be tied to an object, it is display text rather than reliable support for deployment, acceptance, rollback, and incident diagnosis.
A version number is an identifier, not a quality verdict
Version numbers answer which state everyone is discussing. A customer reporting a defect, a tester saving a result, a pipeline deploying an artifact, and an operator rolling back must be able to reference the same object. Without a stable identifier, the phrase latest version changes with time, environment, and speaker.
A larger number does not prove greater stability, security, or acceptance. Version `2.0.0` might be an untested candidate while `1.8.12` is the live production version. Release, acceptance, and production status require separate test, approval, and deployment evidence.
Meaning comes from policy. Two products can both display `X.Y.Z`, while one follows public-API compatibility under Semantic Versioning and the other uses internal milestones. The shape alone does not reveal change size.
How common versioning schemes work
Semantic Versioning
For a declared public API, `MAJOR.MINOR.PATCH` means incompatible API change, backward-compatible functionality, and backward-compatible fix respectively. It supports prerelease identifiers and build metadata that does not affect precedence.
Monotonic release sequence
Numbers such as `v17` or `release-42` make order clear but communicate neither compatibility nor change type, so they require a change log.
Calendar or cycle version
A year, month, quarter, or iteration such as `2026.08` communicates schedule or release period, not compatibility. The policy still handles backports and several builds in one period.
Four-part or platform-specific version
Some runtimes use major, minor, build, and revision fields. .NET has package, assembly, file, and informational versions with different consumers and runtime effects.
Prerelease identifier
Names such as `alpha`, `beta`, and `rc.1` normally indicate a not-yet-normal release. Under SemVer, a prerelease has lower precedence than the corresponding normal version; the project also defines where prereleases may run.
Product or composite version
A customer-facing product version can represent many components, but a manifest must map it to actual frontend, backend, database, model, and configuration versions rather than forcing every component to share one number.
What other identifiers prove
| Identifier | What it does and does not establish |
|---|---|
| Version number | Names a state under a declared policy for communication and comparison; it proves content only after it is bound to an object. |
| Build number | Distinguishes a CI/CD build or pipeline run and traces creation. One product version can have several builds. |
| Git commit ID | Identifies an immutable source commit and history, but not build environment, dependency resolution, configuration, database, or external model state. |
| Artifact digest | A content digest verifies identical binary, image, or manifest bytes. It is machine-friendly but does not express business compatibility. |
| Tag or alias | A mutable pointer such as `latest`, `stable`, or `production` conveniently selects a current target. Once moved, the same name references another object and is insufficient historical evidence. |
| Release date or name | Describes an external release event or marketing name that may group several versions; a built version might never be released. |
What an executable version policy defines
- What is the versioned object?
Name the product, service, API, database schema, configuration package, application, or model. Objects with different lifecycles should not be forced under one number.
Record: object, owner, storage location, and scope.
- What do format and increments mean?
Define fields, characters, ordering, major/minor/patch or calendar semantics, and rules for zero versions, branches, and emergency fixes.
Record: policy with valid and invalid examples.
- When is a number assigned and frozen?
State when development, candidate, acceptance, and formal release numbers are created and whether any content change requires a new number.
Record: generation event, freeze gate, and mutation rule.
- How is it bound to immutable content?
Attach source commit, build run, lockfile, artifact URI and digest, migration, and configuration baseline.
Record: machine-readable version or release manifest.
- What compatibility and support are promised?
If the number communicates API, format, or client compatibility, define the surface, deprecation window, upgrade path, and support life.
Record: compatibility matrix, breaking changes, and support policy.
- Who can release or move an alias?
Restrict formal version creation, retagging, artifact overwrite, and movement of `stable`, and retain an audit trail.
Record: repository protection, signing, approval, and tag log.
- Where can users see it?
Pages, APIs, logs, health endpoints, and support material should reveal enough to diagnose an object without leaking sensitive internals.
Record: version-query and support procedure.
Using version numbers in a project
Choose product and component levels
Define the customer-facing product version and list application, service, database, configuration, and content components that need independent tracking.
Generate the mapping automatically
Write version, commit, build, dependencies, and digest at build time instead of copying them manually into documents.
Promote one artifact across environments
Prefer the same immutable artifact through test, UAT, staging, and production. A rebuild creates a new build and digest even when visible version text is unchanged.
Bind test evidence
Cases, defects, performance reports, security scans, and acceptance decisions record version, build, and environment. A fix is a new object and is retested.
Bind deployment state
Each environment records which product and component versions were deployed, when, by whom, with which configuration, migration, and digest.
Retain rollback objects
Keep earlier artifacts, configuration, migration compatibility, and recovery instructions under policy. A number is useless when its content cannot be recovered.
Why enterprise AI needs a composite version manifest
Application and orchestration
Record frontend, backend, workflow, agent graph, tool definitions, and business rules. Tool arguments or orchestration can change outcomes without an application code change.
Model version or snapshot
Record provider, model ID, fixed snapshot or registry version, region, and deployment name. Mutable aliases such as `latest`, `default`, and `stable` require the concrete version resolved at the time.
Prompts and safety policy
Version system prompts, templates, output schemas, content filters, guardrails, and human-approval rules instead of preserving only the latest text.
Knowledge and retrieval
Record source batch, permission snapshot, cleaning, chunking, embedding model, index build, retrieval, and reranking. A file or index name cannot reproduce knowledge state.
Evaluation set and scorer
Samples, reference answers, rubrics, reviewer calibration, and automated judges also change. Results identify both system and evaluation version to remain comparable.
External services and runtime settings
Include model parameters, tool API versions, third-party rules, feature flags, and material environment configuration. For an unpinned managed dependency, record observation time, change policy, and revalidation trigger.
Concepts commonly confused with version number
| Related concept | Difference |
|---|---|
| Version | A version is the concrete state of an object at a point; its version number is the identifier assigned to that state. A version also includes content and metadata. |
| Build | A build is the process or result of producing an artifact. Retries, platforms, and changed dependencies can create several builds under one displayed version. |
| Release | A release is the business and technical event that makes a version available to an audience. A version number does not prove release. |
| Acceptance version | An acceptance version is the complete baseline formally designated for acceptance. The version number is only one identifier and cannot define acceptance scope alone. |
| Production version | This is the object actually running in production and must be read from deployment state, not inferred from numeric order. |
| Change log | A change log explains what changed, why, and with what impact between versions. The number only provides a reference point. |
Sources and scope
This entry defines a version number used to identify the state of software, a service, configuration, or another changing object. It does not require Semantic Versioning for every project and does not equate a version number with a build number, release date, Git commit, artifact digest, tag, release name, acceptance version, or currently deployed production version. A format and its increments have meaning only when a team declares and consistently follows a versioning policy.
- Semantic Versioning 2.0.0: Major, minor, patch, prerelease, and build-metadata rules
- Microsoft .NET: Package, assembly, file, and informational versions
- Git: Immutable objects, commits, and content identifiers
- Open Container Initiative: Content digests for artifact identification and verification
- GitHub Docs: Release names, tags, and version history
- Google Cloud Vertex AI: Concrete model versions and mutable version aliases