Versioning and changelog - discussion point.

[7sharp9]

Here are some thoughts and points around versioning and change info, there is probably other aspects of this that I have missed but feel free to add these here so we can manage how you want this to evolve to match the changing direction due to productisation, auditing, etc

• 1. Reconcile the two version schemes.
  If someone looks at the GenFORM library, it says version 1.2.4. If they look at the application changelog, it says 0.1.2-alpha. If they look at the Docker image, it could say anything something else. If auditing is a priority then knowing exactly what versions running will be really important. Its also a gap in the technical documentation if new features require and modification or new sections.

  1. Per-library build metadata: Directory.Build.props:11: 1.2.4. This is what gets embedded in the compiled DLL and would appears in a NuGet package. The other five libraries each have their own file with their own number (GenSOLVER is 1.0.0, GenUNITS is 1.0.3, etc.).
  2. Application changelog - CHANGELOG.md:129: ## [0.1.2-alpha] - 2026-03-23. This is a 0.x versioning scheme, completely separate from the 1.x library scheme above. It describes the whole application - server, client, all libraries together.
  3. The [Unreleased] block - CHANGELOG.md:8: changes since March 2026 that have no version number at all yet.

• 2. Add a root-level version file.
  This is the fix that makes the version machine-readable in one place. Instead of the version living only in a changelog document , it lives in a project file that build tools, Docker, and CI can all read automatically. You'd never again have to manually keep a Docker image tag, a changelog entry, and a library file in sync - they'd all derive from the same source of truth. I use a simple version for this in Myriad and my audio plugin work, admittedly I don't have many modules so its a lot simpler in mt case.

• 3. Higher cadence for releases to ensure .
  The [Unreleased] section has been accumulating since March 2026. It contains a full rewrite of the dose-check compliance logic, a security hardening pass, and a Fable 5 upgrade.

• 4. Add a PR title check. There is already a well-written convention for commit messages for AI/agents (commit-message.instructions.md). The problem is its not enforced anywhere. A contributor (human or AI) could merge a PR with a message like "fix stuff" and it would violate the standard that you are enforcing via the agentic path. A single automated check on the PR title could turn a written rule into a real technical gate for everyone committing. It also makes changelog generation easier later, because you can trust the history is structured text, or at least you know the exact structure this text will form for future automation via parsing etc.

• 5. Address the build in terms of client/server split. Only build the necessary parts for client OR server rather than everything, this will allow a separate server/client solution once the relevant parts are complete.

• 6. Automate the release as a build target.
  Currently, building a release means:

  • edit CHANGELOG.md in the right format,
  • remember to update six library version files,
  • remember to create a git tag,
  • remember to push it.

Each of those steps is an opportunity to forget something or make a typo. Wrapping this in a FAKE target means you type one command and all of it this happens consistently. More importantly all these steps get done in one operation and nothing should get out of sync, this would make auditing an easier operation.

Some of these will need discussion, esp points 1/2. Due to process and historical evolution of the repo etc. Point 4. Add a PR title check is quick and easy and starts to enforce the shape of the commit/PR entries.

[halcwb]

I agree on all points. There is a lot of legacy lingering about. Thanks.

[7sharp9]

So based on the discussion above that I presented we now have a choice:

One version number for the whole app, or separate numbers for each library plus one number for the app?

Option A: One number for everything

Every part of GenPRES: - the app, all libraries, the Docker image all share the same version number, updated together at release time.

• Pros: Dead simple. One number tells you exactly what's running. Easy to audit.
• Cons: A library gets its version bumped even in releases where nothing in it changed. The number stops meaning, this library changed, and just becomes: a release happened.

Option B: Keep libraries separate, add one app-level number

The libraries keep their own version numbers as they do now. A new, single number is added just for the app as a whole that is the one used in the changelog, the Docker image, and anywhere where an audit matters. The library numbers become internal detail nobody outside the team needs to look at.

• Pros: No disruption to what already exists. Libraries can still make sense of their own version history if anyone ever needs it.
• Cons: You still have two systems running side by side. An auditor has to be told that the two numbers aren't related and that information has to be recorded somewhere, and stay accurate.

In my naive opinion, Option A makes sense, unless you have concrete plans to publish the libraries independently soon?

@halcwb ^

[halcwb]

@7sharp9 Correct to go with option A. Option B was sort of legacy as in the past I tried to develop the core libraries more independently. For now, that is really not necessary.

[7sharp9]

Based on option A here's a fleshed out plan, this needs diffing against what easyshipit does too to ensure we don't make a rounder wheel.

Versioning & CI hardening

CI: commit message enforcement

• Add CI check that lints every commit in a PR against commit-message.instructions.md (.github/workflows/commit-lint.yml)
• Add commit-lint to master's required status checks (repo admin action — not yet done, check currently reports but doesn't block merge)
• Decide whether to enable enforce_admins on branch protection so required checks can't be bypassed (bigger decision, applies to all required checks, not just this one)

Decision needed: starting version number

• Decide whether the first unified release is 0.1.3-alpha (continues the existing app sequence) or a new number like 0.2.0 (marks the scheme change explicitly)

Version scheme unification (single version for app + libraries)

• Add root-level Directory.Build.props with one <Version>
• Update all six library Directory.Build.props files:
  • (GenFORM, GenORDER, GenSOLVER, GenUNITS, NKF, Utils) to import the root version instead of declaring their own. Do this in one step so everything stays aligned.
• Build and verify the version actually propagates to dlls properly rather rely on CI output, belt and braces.
• Re-confirm no .fsproj in the solution overrides the new Version/PackageVersion after the change.

Docker image versioning

• Add ARG APP_VERSION + LABEL org.opencontainers.image.version to the Dockerfile so it gets the correct single curated version.
• Update the local docker-local.sh / docker-amd64.sh script templates (documented in DEVELOPMENT.md) to pass --build-arg APP_VERSION=... read from the root Directory.Build.props
• Keep the version extraction logic in the shell wrapper scripts so it can be used in mutiple places

Documentation

• Write an ADR (docs/mdr/design-history/0022-*.md) documenting the option A decision

Git tags

• Start tagging releases (git tag vX.Y.Z, pushed). The repo currently has zero tags, and release automation depends on this part. This may eb manual and automated where major releases need a manual button to do the work, and incremental fixes use automation.

Release automation

• Add a FAKE build target that: bumps the root Directory.Build.props version, updates CHANGELOG.md's [Unreleased] header to [X.Y.Z] - date, creates and pushes a git tag
• Wire the release target to build and label the Docker image with the new version

Process

• Agree a release cadence, when does [Unreleased] change to the next version? Is it driven from sprint backlog or date based milestones etc.