Operations Introductory 2 minute read Updated 2026-06-26 UTC

Versioning and release notes

A simple SemVer-style release discipline for a content-heavy PHP research site.

Research statusOperations practice guide Publication statePublished Reviewed byMichael Kappel Source reports0

Version files

ModelBreeder.com uses three version surfaces:

FileRole
VERSIONsingle-line package version
CHANGELOG.mdchronological changes
RELEASES.mdrelease checklist, deployment notes, and rollback notes
config/site.phpversion shown on the public site
config/uai.phpversion used by the memory package
build-manifest.jsongenerated release evidence

All of them should agree for a release package.

Versioning rule

Use MAJOR.MINOR.PATCH.

  • Increment PATCH for typo fixes, small content edits, and non-breaking validation changes.
  • Increment MINOR for new sections, new pages, new memory structure, layout changes, or deployment layout changes.
  • Increment MAJOR for incompatible runtime assumptions, deleted public routes, or changed storage model.

v1.2.0 is a minor release because it changes deployment layout and UAI memory mode while preserving public site behavior. v1.2.1 is a patch release because it fixes live URL generation without changing the content model, route map, or memory schema.

pseudocode
FUNCTION classify_release(changes)
    IF changes.break_public_routes OR changes.require_new_runtime_model
        RETURN "major"
    IF changes.add_pages OR changes.change_deployment_layout OR changes.change_memory_mode
        RETURN "minor"
    RETURN "patch"
END FUNCTION

Release evidence

A release is not just a ZIP. It needs evidence:

  • build output;
  • route smoke tests;
  • report hash verification;
  • UAI memory validation;
  • clean extraction test;
  • archive path-safety test;
  • SHA-256 checksum.

Rollback note

Because this is a file-backed site, rollback is replacing the extracted files with the prior package and clearing opcode/cache layers if the host uses them. Do not edit files directly in production without bringing those changes back into the release package.