From 09b29a43e1433cdbb58692df3fa0066ee3ea65a3 Mon Sep 17 00:00:00 2001 From: wlthomson Date: Fri, 3 Jul 2026 13:48:13 +1200 Subject: [PATCH 1/5] Remove unsafe release expression --- src/pages/docs/releases/release-versioning.md | 28 ++++++++----------- 1 file changed, 11 insertions(+), 17 deletions(-) diff --git a/src/pages/docs/releases/release-versioning.md b/src/pages/docs/releases/release-versioning.md index 4e609ec9d5..7f3716207c 100644 --- a/src/pages/docs/releases/release-versioning.md +++ b/src/pages/docs/releases/release-versioning.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2024-05-20 +modDate: 2026-07-02 title: Release versioning description: Select how the next release number is generated when creating a release. icon: fa-solid fa-code-commit @@ -81,26 +81,20 @@ A relatively common versioning scheme is: YEAR.MONTH.DAY.REVISION ``` -where `REVISION` starts at 0 each day and increments with each release. i.e. The releases on one day might be `2020.10.2.0`, `2020.10.2.1`, `2020.10.2.2` ... and the following day may be: `2020.10.3.0`, `2020.10.3.1` etc. +where `REVISION` starts at 0 each day and increments with each release. i.e. The releases on one day might be `2020.10.2.0`, `2020.10.2.1`, `2020.10.2.2` ... and the following day may be: `2020.10.3.0`, `2020.10.3.1` etc. This can be achieved using the following expression: -``` -#{Octopus.Date.Year}.#{Octopus.Date.Month}.#{Octopus.Date.Day}. -#{if Octopus.Date.Day==Octopus.Version.LastPatch} -#{Octopus.Version.NextRevision} -#{else} -#{if Octopus.Version.LastRevision!=0} -0 -#{else} -#{Octopus.Version.NextRevision} -#{/if}#{/if} -``` - -The expression above is equivalent to: - ``` #{Octopus.Date.Year}.#{Octopus.Date.Month}.#{Octopus.Date.Day}.i ``` -The difference is that the `i` is not replaced until the release is saved where the complex expression will show the next increment number before it is saved. +The `i` mask character increments the previous release's revision component by one on every release. Note +that the revision component will reset whenever any part of the date changes from the previous release. + +:::div{.warning} +We do not recommend comparing version and date components for equality (e.g. +`#{if Octopus.Date.Day==Octopus.Version.LastPatch}`). `Octopus.Date.Day`/`Month` are zero-padded (`01`), while +`Octopus.Version.Last*`/`Next*` variables are not (`1`). This introduces the possibility for comparisons to +unexpectedly fail on single-digit days or months, causing unexpected version conflicts. +::: From ff65033552dcd69024ca15bc3f0257fbc844930b Mon Sep 17 00:00:00 2001 From: wlthomson Date: Fri, 3 Jul 2026 15:35:53 +1200 Subject: [PATCH 2/5] Make markdownlint happy again --- src/pages/docs/releases/release-versioning.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/src/pages/docs/releases/release-versioning.md b/src/pages/docs/releases/release-versioning.md index 7f3716207c..734cd6487a 100644 --- a/src/pages/docs/releases/release-versioning.md +++ b/src/pages/docs/releases/release-versioning.md @@ -22,62 +22,62 @@ Within a project, click **Settings ➜ Release Versioning**: You can use variables from the project (un-scoped or scoped only to a channel). In addition, some special variables are provided - example: -``` +```text 1.2.#{Octopus.Version.NextPatch}-pre ``` These special variables take the form: -``` +```text Octopus.Version.(Last|Next)(Major|Minor|Patch|Build|Revision|Suffix) ``` If you are using channels, channel-specific special variables are also available: -``` +```text Octopus.Version.Channel.(Last|Next)(Major|Minor|Patch|Build|Revision|Suffix) ``` Version components from other channels in the project can be referenced using the channel name as the index: -``` +```text Octopus.Version.Channel[ChannelName].(Last|Next)(Major|Minor|Patch|Build|Revision|Suffix) ``` The channel name can also be used (generally as part of the suffix): -``` +```text Octopus.Release.Channel.Name ``` The version can also include Octopus *semantic version mask* characters i and c referring to the **incremented** and **current** values of the version, respectively. For example: -``` +```text 2.1.c.i ``` Finally, date fields can be also be used, for example: -``` +```text #{Octopus.Date.Year}.#{Octopus.Date.Month}.#{Octopus.Date.Day} ``` These take the form: -``` +```text Octopus.Date.(Day|Month|Year|DayOfYear) Octopus.Time.(Hour|Minute|Second) ``` ## Complex expressions -The full power of the [Octopus variable syntax](/docs/projects/variables/variable-substitutions/#complex-syntax) (powered by [Octostache](https://github.com/OctopusDeploy/Octostache)) is available in version templates. In particular, [conditional expressions](/docs/projects/variables/variable-substitutions/#conditionals) can be used to model some complex scenarios. +The full power of the [Octopus variable syntax](/docs/projects/variables/variable-substitutions/#complex-syntax) (powered by [Octostache](https://github.com/OctopusDeploy/Octostache)) is available in version templates. In particular, [conditional expressions](/docs/projects/variables/variable-substitutions/#conditionals) can be used to model some complex scenarios. ### Example: Date with incrementing revision -A relatively common versioning scheme is: +A relatively common versioning scheme is: -``` +```text YEAR.MONTH.DAY.REVISION ``` @@ -85,7 +85,7 @@ where `REVISION` starts at 0 each day and increments with each release. i.e. The This can be achieved using the following expression: -``` +```text #{Octopus.Date.Year}.#{Octopus.Date.Month}.#{Octopus.Date.Day}.i ``` From e5b7dfb97b5f09106e041e20549dd9c46f8a2341 Mon Sep 17 00:00:00 2001 From: wlthomson Date: Fri, 3 Jul 2026 16:39:18 +1200 Subject: [PATCH 3/5] Add fixed versioning complex expression with warning --- src/pages/docs/releases/release-versioning.md | 29 ++++++++++++++----- 1 file changed, 22 insertions(+), 7 deletions(-) diff --git a/src/pages/docs/releases/release-versioning.md b/src/pages/docs/releases/release-versioning.md index 734cd6487a..1a647778cb 100644 --- a/src/pages/docs/releases/release-versioning.md +++ b/src/pages/docs/releases/release-versioning.md @@ -85,16 +85,31 @@ where `REVISION` starts at 0 each day and increments with each release. i.e. The This can be achieved using the following expression: +```text +#{Octopus.Date.Year}.#{Octopus.Date.Month}.#{Octopus.Date.Day}. +#{if Octopus.Date.Day==Octopus.Version.LastPatch | Format Int32 D2} +#{Octopus.Version.NextRevision} +#{else} +#{if Octopus.Version.LastRevision!=0} +0 +#{else} +#{Octopus.Version.NextRevision} +#{/if}#{/if} +``` + +:::div{.warning} +We do not recommend comparing version and date components for equality (e.g. #{if +Octopus.Date.Day==Octopus.Version.LastPatch}). Octopus.Date.Day/Month are zero-padded (01), while +Octopus.Version.Last\*/Next\* variables are not (1). This introduces the possibility for comparisons to +unexpectedly fail on single-digit days or months, causing unexpected version conflicts. While piping through +Format Int32 D2 works around this, we recommend the simpler mask-based expression below instead. +::: + +Instead, use the following simpler mask-based expression: + ```text #{Octopus.Date.Year}.#{Octopus.Date.Month}.#{Octopus.Date.Day}.i ``` The `i` mask character increments the previous release's revision component by one on every release. Note that the revision component will reset whenever any part of the date changes from the previous release. - -:::div{.warning} -We do not recommend comparing version and date components for equality (e.g. -`#{if Octopus.Date.Day==Octopus.Version.LastPatch}`). `Octopus.Date.Day`/`Month` are zero-padded (`01`), while -`Octopus.Version.Last*`/`Next*` variables are not (`1`). This introduces the possibility for comparisons to -unexpectedly fail on single-digit days or months, causing unexpected version conflicts. -::: From 266c1ab10498a95c9a2a8801df417844d04e85fb Mon Sep 17 00:00:00 2001 From: wlthomson Date: Fri, 3 Jul 2026 17:09:28 +1200 Subject: [PATCH 4/5] Tidy up presentation --- src/pages/docs/releases/release-versioning.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/src/pages/docs/releases/release-versioning.md b/src/pages/docs/releases/release-versioning.md index 1a647778cb..6c1f0d476e 100644 --- a/src/pages/docs/releases/release-versioning.md +++ b/src/pages/docs/releases/release-versioning.md @@ -98,15 +98,11 @@ This can be achieved using the following expression: ``` :::div{.warning} -We do not recommend comparing version and date components for equality (e.g. #{if -Octopus.Date.Day==Octopus.Version.LastPatch}). Octopus.Date.Day/Month are zero-padded (01), while -Octopus.Version.Last\*/Next\* variables are not (1). This introduces the possibility for comparisons to -unexpectedly fail on single-digit days or months, causing unexpected version conflicts. While piping through -Format Int32 D2 works around this, we recommend the simpler mask-based expression below instead. +This example is no longer recommended for production workloads due to the potential for unexpected version +conflicts arising from inconsistencies between date formats. The following simple mask-based expression +should be preferred: ::: -Instead, use the following simpler mask-based expression: - ```text #{Octopus.Date.Year}.#{Octopus.Date.Month}.#{Octopus.Date.Day}.i ``` From cbd3110fc8bb9e37b3b986b1885ddba3774fab76 Mon Sep 17 00:00:00 2001 From: wlthomson Date: Fri, 3 Jul 2026 17:37:11 +1200 Subject: [PATCH 5/5] Improve warning phrasing --- src/pages/docs/releases/release-versioning.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/releases/release-versioning.md b/src/pages/docs/releases/release-versioning.md index 6c1f0d476e..84a98af0f2 100644 --- a/src/pages/docs/releases/release-versioning.md +++ b/src/pages/docs/releases/release-versioning.md @@ -99,8 +99,8 @@ This can be achieved using the following expression: :::div{.warning} This example is no longer recommended for production workloads due to the potential for unexpected version -conflicts arising from inconsistencies between date formats. The following simple mask-based expression -should be preferred: +conflicts arising from inconsistencies between date formats. The mask-based alternative provided below +should be preferred. ::: ```text