[DISCUSSION]: New Release Version Considerations #236

New Issue

2025-11-05T00:14:26Z

AaronFiore commented

2025-11-05 00:14:26 +00:00

(Migrated from gitea.com)

This issue will track ongoing discussion from #docker-finance:matrix.org regarding a new hybrid semver/rolling release system.

2025-11-03

With regard to versioning considerations, there are at least 3 current primary components to the dfi build system:

Public consuming API interfaces
   - fetch (php)
   - root (c++)
   - plugins (bash, c++)
Remote Docker build states (dependencies)
   - Arch Linux OS
     * rolling: YYYYMMDD.0.build_number
       - currently we're using latest but that could be changed (but see point 3)
   - Ubuntu OS
     * rolling: name-YYYYMMDD
       - currently we're using latest but that could be changed (but see point 3)
   - dfi images
     * tagged by platform: archlinux / ubuntu / dev-tools
       - a single tag per platform means no rollback potential (but see point 3)
Local Docker build states (locally built)
- This is dependent upon end-user custom build types (default, slim, tiny, micro)
* These are ultimately determined per-module (fetch, track, root, etc.)

Within point 3 are various dependencies (such as ccxt) that are installed upon first build or every update (their latest stable releases), mostly regardless of whether point 2 is bumped. Also, since point 3 will always update/upgrade pacman -Syu / apt-get update/upgrade), tracking by point 2 only seems not very useful at the moment.

Simply put: a more tenable dfi solution (to this relatively uncommon type of cross-platform dependency hell) may be to deploy a hybrid of rolling release/semver.

WIP proposals:

MAJOR.MINOR.PATCH+YYYYMMDD.epoch | e.g., v1.0.0+20251103.1762204451
   - MAJOR.MINOR.PATCH tracks dfi codebase
     * MAJOR tracks point 1 above (public APIs)
     * MINOR and PATCH tracks the rest, as defined by typical semver
   - +YYYYMMDD tracks:
     * date that dfi remote images are created/pushed
   - .epoch allows for multiple same-day releases w/out needing to manually increment (e.g., date --utc +%s)
MAJOR+YYYYMMDD.epoch | e.g., v1.20251103.1762204451
   - drops MINOR and PATCH for a more simplified v1 public API (as seen above)
   - +YYYYMMDD tracks:
     * any code changes between previous date release
     * date that dfi remote images are created/pushed
   - .epoch allows for multiple same-day releases w/out needing to manually increment (e.g., date --utc +%s)
MAJOR.MINOR.PATCH+YYYYMMDD.epoch where MAJOR.MINOR.PATCH ONLY tracks the public API and +YYYYMMDD tracks any/all code changes between previous date release and that release - including dfi re-built remote images (as seen above). .epoch also still applies.

2025-11-04

[Though projects exist that utilize a collection of software,] there are none with these specific constraints that I can find; specifically, programmability and interoperable local builds.

Some other projects will simply go flat (linear) and track a single underlying primary dependency’s version - incrementing metadata for only image rebuilds - but those rebuilds also include all other dependency version changes (e.g., docker-swag). I’ve also seen a project completely ditch versioning all together and just work from a single master branch with no tags or releases (working successfully for years now).

In all cases, as long as they’re pulling from an OS image where the underlying packages are stable, everything from the top down appears to work until it doesn’t (but this would affect any user of any package at any time). When that happens, like a developer pulling from a different library version, end-users can pull different package version via their various distro channels. As for dfi, that can easily be done with dfi <platform/${USER}:tag> edit type=build and then add the subsequent Dockerfile commands to pull from a “working” package (again, very rare for this to be needed, IMHO, and it’s a PITA regardless of dfi).

With that said, I’m leaning towards the 1st proposal but with the following changes/clarifications:

WIP proposal

MAJOR.MINOR.PATCH tracks dfi (and most public-facing API) but all dependency versions are treated as dev dependencies - and thus do not increment PATCH.
- The underlying dfi system has always been rolling release and the drawbacks of that have been exceedingly rare. End users can always dfi <platform/${USER}:tag> update type=<type> to stay in sync with upstream stable dependency versions at any time (just like a typical system update).
  - I think this works because dfi really does act as a quasi-”financial operating system” more-so than an “application” or “library”.
+YYYYMMDD tracks dfi remote build images
- These images could include any updates to dependencies – or not.
- For example: hypothetically, if dfi v1.0.0 doesn’t see a patch for a month but hledger has a point release, we will then update the remote dfi Dockerfiles, remote dfi images are updated/rebuilt/pushed, we then commit the dfi changes and increment build metadata then push the tag.
- To clarify: since hledger would be treated as a dev dependency, only the remote dfi images will be re-built and dfi would be tagged as such only to indicate the latest build with latest dependencies are in the remote images. From there, the end-user can get those updates simply with dfi <platform/${USER}:tag> update type=<type> or do a fresh build if desired.
.epoch or perhaps a simple increment would keep its purpose, AFAICT.

The more I think about it, the more simple I think it becomes because it’s really as straightforward as ‘sitting down at your computer and updating your system’. The reliance on public consuming APIs is limited (and would be tracked via semver anyway) so it’s more aligned as an quasi-”financial operating system” with limited contracts than not (with the major exception being hledger rules but that’s mostly internal anyway).

So, to the simplest end-user view would be, in any order:

Use the build or update command for the +YYYYMMDD.epoch changes
git pull <branch> --tags or similar for the MAJOR.MINOR.PATCH changes
Check CHANGELOG for caveats etc.
For any dependencies: dfi <platform/${USER}:tag> version type=<type> exists and makes it easy to see what dfi and dependency versions are in use (for bugs/issues or general information)

This issue will track ongoing discussion from `#docker-finance:matrix.org` regarding a new hybrid semver/rolling release system. --- 2025-11-03 With regard to versioning considerations, there are at least 3 current primary components to the `dfi` build system: 1. Public consuming API interfaces - `fetch` (php) - `root` (c++) - `plugins` (bash, c++) 2. Remote Docker build states (dependencies) - Arch Linux OS * rolling: `YYYYMMDD.0.build_number` - currently we're using latest but that *could* be changed (but see point 3) - Ubuntu OS * rolling: `name-YYYYMMDD` - currently we're using latest but that *could* be changed (but see point 3) - `dfi` images * tagged by platform: `archlinux` / `ubuntu` / `dev-tools` - a single tag per platform means no rollback potential (but see point 3) 3. Local Docker build states (locally built) - This is dependent upon end-user custom build types (`default`, `slim`, `tiny`, `micro`) * These are ultimately determined per-module (`fetch`, `track`, `root`, etc.) Within point 3 are various dependencies (such as `ccxt`) that are installed upon first build or every update (their latest stable releases), mostly regardless of whether point 2 is bumped. Also, since point 3 will always update/upgrade `pacman -Syu` / `apt-get update/upgrade`), tracking by point 2 only seems not very useful at the moment. Simply put: a more tenable `dfi` solution (to this relatively uncommon type of cross-platform dependency hell) may be to deploy a hybrid of rolling release/semver. WIP proposals: 1. `MAJOR.MINOR.PATCH+YYYYMMDD.epoch` | e.g., `v1.0.0+20251103.1762204451` - `MAJOR.MINOR.PATCH` tracks `dfi` codebase * `MAJOR` tracks point 1 above (public APIs) * `MINOR` and `PATCH` tracks the rest, as defined by typical semver - `+YYYYMMDD` tracks: * date that `dfi` remote images are created/pushed - `.epoch` allows for multiple same-day releases w/out needing to manually increment (e.g.,` date --utc +%s`) 2. `MAJOR+YYYYMMDD.epoch` | e.g., `v1.20251103.1762204451` - drops `MINOR` and `PATCH` for a more simplified v1 public API (as seen above) - `+YYYYMMDD` tracks: * any code changes between previous date release * date that `dfi` remote images are created/pushed - .epoch allows for multiple same-day releases w/out needing to manually increment (e.g., `date --utc +%s`) 3. `MAJOR.MINOR.PATCH+YYYYMMDD.epoch` where `MAJOR.MINOR.PATCH` *ONLY* tracks the public API and `+YYYYMMDD` tracks any/all code changes between previous date release and that release - including `dfi` re-built remote images (as seen above). `.epoch` also still applies. --- 2025-11-04 [Though projects exist that utilize a collection of software,] there are none with these specific constraints that I can find; specifically, programmability and interoperable local builds. Some other projects will simply go flat (linear) and track a single underlying primary dependency’s version - incrementing metadata for only image rebuilds - but those rebuilds also include *all other* dependency version changes (e.g., `docker-swag`). I’ve also seen a project completely ditch versioning all together and just work from a single master branch with no tags or releases (working successfully for years now). In all cases, as long as they’re pulling from an OS image where the underlying packages are stable, everything from the top down appears to work until it doesn’t (but this would affect any user of any package at any time). When that happens, like a developer pulling from a different library version, end-users can pull different package version via their various distro channels. As for `dfi`, that can easily be done with `dfi <platform/${USER}:tag> edit type=build` and then add the subsequent Dockerfile commands to pull from a “working” package (again, very rare for this to be needed, IMHO, and it’s a PITA regardless of `dfi`). With that said, I’m leaning towards the 1st proposal but with the following changes/clarifications: WIP proposal 4. - `MAJOR.MINOR.PATCH` tracks `dfi` (and most public-facing API) but *all* dependency versions are treated as dev dependencies - and thus do *not* increment `PATCH`. - The underlying `dfi` system has *always* been rolling release and the drawbacks of that have been exceedingly rare. End users can always `dfi <platform/${USER}:tag> update type=<type>` to stay in sync with upstream stable dependency versions at any time (just like a typical system update). - I think this works because `dfi` really does act as a quasi-”financial operating system” more-so than an “application” or “library”. - `+YYYYMMDD` tracks `dfi` remote build images * These images could include any updates to dependencies – or not. * For example: hypothetically, if `dfi` v1.0.0 doesn’t see a patch for a month but `hledger` has a point release, we will then update the remote `dfi` Dockerfiles, remote `dfi` images are updated/rebuilt/pushed, we then commit the `dfi` changes and increment build metadata then push the tag. * To clarify: since `hledger` would be treated as a dev dependency, only the remote `dfi` images will be re-built and `dfi` would be tagged as such only to indicate the latest build with latest dependencies are in the remote images. From there, the end-user can get those updates simply with `dfi <platform/${USER}:tag> update type=<type>` or do a fresh `build` if desired. - `.epoch` or perhaps a simple increment would keep its purpose, AFAICT. The more I think about it, the more simple I think it becomes because it’s really as straightforward as ‘sitting down at your computer and updating your system’. The reliance on public consuming APIs is limited (and would be tracked via semver anyway) so it’s more aligned as an quasi-”financial operating system” with limited contracts than not (with the major exception being hledger rules but that’s mostly internal anyway). So, to the simplest end-user view would be, in any order: 1. Use the `build` or `update` command for the `+YYYYMMDD.epoch` changes 2. `git pull <branch> --tags` or similar for the `MAJOR.MINOR.PATCH` changes 3. Check CHANGELOG for caveats etc. 4. For any dependencies: `dfi <platform/${USER}:tag> version type=<type>` exists and makes it easy to see what `dfi` and dependency versions are in use (for bugs/issues or general information)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Reference: EvergreenCrypto/docker-finance#236