Document non-SemVer package ordering on channel package version rules

src/pages/docs/packaging-applications/create-packages/versioning.md

@@ -13,20 +13,22 @@ The [Package ID](/docs/packaging-applications/#package-id), version number, and
 
 The technology you're working with will, in some cases, determine the type of versioning scheme you choose. We recommend using [Semantic Versioning](#semver) for your applications, unless you are deploying artifacts to a [Maven repository](/docs/packaging-applications/package-repositories/maven-feeds), in which case, you need to use [Maven Versions](#maven).
 
+If your toolchain produces version strings that don't sort correctly under SemVer (for example feature-branch names, CI build numbers, or date-stamped builds), channels can be configured to order packages by [publish date](/docs/releases/channels#version-ordering-strategy) instead of version string — letting feed triggers and release creation pick the most-recently-published version.
+
 Consider the following factors when deciding on the versioning scheme you'll use for your applications and packages:
 
 1. Can you trace a version back to the commit/check-in the application/package was built from?
 
-  *For example: We stamp the SHA hash of the git commit into the metadata component of the Semantic Version for Octopus Deploy which makes it easier to find and fix bugs. We also tag the commit with the version of Octopus Deploy it produced so you can quickly determine which commit produced a particular version of Octopus Deploy.*
+   *For example: We stamp the SHA hash of the git commit into the metadata component of the Semantic Version for Octopus Deploy which makes it easier to find and fix bugs. We also tag the commit with the version of Octopus Deploy it produced so you can quickly determine which commit produced a particular version of Octopus Deploy.*
 
 2. Can your users easily report a version to the development team that supports #1?
 3. Will your version numbers be confusing, or will they help people understand the changes that have been made to the software?
 
-  *For example: bumping a major version component (first part) means there are potentially breaking changes, but bumping a patch (3rd part) should be safe to upgrade, and safe to rollback if something goes wrong.*
+   *For example: bumping a major version component (first part) means there are potentially breaking changes, but bumping a patch (3rd part) should be safe to upgrade, and safe to rollback if something goes wrong.*
 
 4. Does your tool chain support the versioning scheme?
 
-  *Octopus supports Semantic Versioning, which enables enhanced features like [Channels](/docs/releases/channels).*
+   *Octopus supports Semantic Versioning, which enables enhanced features like [Channels](/docs/releases/channels).*
 
 ## SemVer {#semver}
 
@@ -70,7 +72,7 @@ Octopus uses a string-based approach to version numbers. These are the decisions
         i. `3.0.0-beta.10 > 3.0.0-beta.9`  
         i. `1.4.008 < 1.4.9`  
 
- 3. **Package Feeds:** Octopus asks the feed for a package with the version string stored in the release, and accepts what the feed provides.
+3. **Package Feeds:** Octopus asks the feed for a package with the version string stored in the release, and accepts what the feed provides.
 
 ## Maven versions {#maven}
 
@@ -80,23 +82,23 @@ The Maven versioning scheme is implemented as a copy of the [ComparableVersion](
 
 Maven version strings have 5 parts:
 
-* Major
-* Minor
-* Patch
-* Build number
-* Qualifier
+- Major
+- Minor
+- Patch
+- Build number
+- Qualifier
 
 The Major, Minor, Patch, and Build number are all integer values.
 
 The Qualifier can hold any value, although some qualifiers have special meanings and an associated order of precedence as follows:
 
-* alpha or a
-* beta or b
-* milestone or m
-* rc or cr
-* snapshot
-* (the empty string) or ga or final
-* sp
+- alpha or a
+- beta or b
+- milestone or m
+- rc or cr
+- snapshot
+- (the empty string) or ga or final
+- sp
 
 Qualifiers are case-insensitive, and some of the qualifiers have shorthand aliases, for instance, `alpha` and `a`. If you use an alias it must include a number, for instance, `a1`. If you do not include a number after the alias, it will be treated as an unrecognized qualifier which will be compared as a case-insensitive string after the qualified versions.
 
@@ -108,10 +110,10 @@ For an in-depth look at Maven versions, see the blog post [Maven Versions Explai
 
 ## Learn more
 
- - [Package your applications](/docs/packaging-applications).
- - [Create packages with Octopus CLI](/docs/packaging-applications/create-packages/octopus-cli).
- - [Creating packages with OctoPack](/docs/packaging-applications/create-packages/octopack).
- - [TeamCity plugin](/docs/packaging-applications/build-servers/teamcity).
- - [Azure DevOps plugin](/docs/packaging-applications/build-servers/tfs-azure-devops/using-octopus-extension).
- - [Package repositories](/docs/packaging-applications).
- - [Package deployments](/docs/deployments/packages).
+- [Package your applications](/docs/packaging-applications).
+- [Create packages with Octopus CLI](/docs/packaging-applications/create-packages/octopus-cli).
+- [Creating packages with OctoPack](/docs/packaging-applications/create-packages/octopack).
+- [TeamCity plugin](/docs/packaging-applications/build-servers/teamcity).
+- [Azure DevOps plugin](/docs/packaging-applications/build-servers/tfs-azure-devops/using-octopus-extension).
+- [Package repositories](/docs/packaging-applications).
+- [Package deployments](/docs/deployments/packages).

src/pages/docs/projects/project-triggers/external-feed-triggers.md

@@ -94,7 +94,7 @@ When you are using external feed triggers there are a few reasons why a release
 
 4. Ensure you are pushing a **new version** of the package - Octopus will not create a release where the package has already been used for creating a release.
 
-5. Ensure you are pushing a package that Octopus will consider as the **latest available package**. The trigger's version evaluator uses SemVer, and will not trigger off image tags such as 'latest'.
+5. Ensure you are pushing a package that Octopus will consider as the **latest available package**. By default, the trigger's version evaluator uses SemVer and will not trigger off image tags such as `latest`. If your packages don't follow SemVer (for example feature-branch tags or date-stamped builds), configure the channel's package version rule to use [Most recently published](/docs/releases/channels#version-ordering-strategy) ordering, which ranks candidates by the publish date that the feed reports. Most recently published is not supported on container or OCI registry feeds — see the feed support note in the channel rules docs.
 
 6. Make sure that the feed and package references only use variables which are **able to be evaluated at release creation time.** For example, the environment name variable is not available, because it is only known at the time of deployment.
 

src/pages/docs/releases/channels/index.md

@@ -78,17 +78,18 @@ When creating a release for a channel with rules, an option can be configured on
 
 Package version rules assist in selecting the correct versions of packages for the channel.  They are only used when creating a release, either manually or via [project triggers](/docs/projects/project-triggers).
 
-:::div{.hint}
-Version rules will work best when you follow [Semantic Versioning (SemVer 2.0.0)](http://semver.org) for your versioning strategy.
-:::
+By default, channels rank package versions using [Semantic Versioning (SemVer 2.0.0)](http://semver.org). If your packages don't follow SemVer — feature-branch tags, date-stamped builds, CI build numbers — you can rank them by publish date instead, using the [Most recently published](#version-ordering-strategy) ordering strategy.
 
 1. When viewing a channel, click **Add rule** in the Package Version Rules section.
 2. Select the package step(s) (and as such the packages) the version rule will be applied to.
-3. Enter the version range in the **Version range** field. You can use either [Nuget](https://oc.to/NuGetVersioning) or [Maven](https://oc.to/MavenVersioning) versioning syntax to specify the range of versions to include.
+3. Select an [ordering strategy](#version-ordering-strategy):
+    - **Use semantic version** (default) — rank packages by their version string using SemVer comparison. Continue at step 4.
+    - **Use most recently published** — rank packages by the publish date that the feed reports. Skip to the [Most recently published rules](#most-recently-published-rules) section below.
+4. Enter the version range in the **Version range** field. You can use either [Nuget](https://oc.to/NuGetVersioning) or [Maven](https://oc.to/MavenVersioning) versioning syntax to specify the range of versions to include.
 
     You can use the full semantic version as part of your version range specification. For example: `[2.0.0-alpha.1,2.0.0)` will match all 2.0.0 pre-releases (where the pre-release component is `>= alpha.1`), and will exclude the 2.0.0 release.
 
-4. Enter any pre-release tags you want to include.
+5. Enter any pre-release tags you want to include.
 
     Following the standard 2.0.0 [SemVer syntax](http://semver.org/), a pre-release tag is the alphanumeric text that can appear after the standard *major.minor.patch* pattern immediately following a hyphen. Providing a regex pattern for this field allows the channel to filter packages based on their tag in a very flexible manner.  The [SemVer build metadata](https://semver.org/#spec-item-10) will also be evaluated by the regex pattern. Some examples are.
 
@@ -107,15 +108,52 @@ Version rules will work best when you follow [Semantic Versioning (SemVer 2.0.0)
     If adding a pre-release tag to channels, you will also need to add the tag `^$` to your `default` channel
     :::
 
-5. Click **Design rule**.
+6. Click **Design rule**.
 
     The **Design Version Rule** window will show a list of the packages that will deployed as part of the deploy package step selected earlier. The versions of the packages that will deployed in this channel with the version rules you've designed will be highlighted in green, and the versions of the packages that will not be deployed with be shown in red. You can continue to edit the version rules in this window.
 
     :::figure
     ![Design version rule](/docs/img/releases/channels/images/channel-design-version-rule.png)
     :::
 
-6. Click **Save**.
+7. Click **Save**.
+
+#### Ordering strategy {#version-ordering-strategy}
+
+:::div{.hint}
+The **Use most recently published** ordering strategy is currently behind the `non-semver-ordering` feature toggle. While the toggle is disabled, the ordering strategy choice is unavailable and channels rank package versions using SemVer.
+:::
+
+Channels rank candidate package versions to decide which is the "latest" that satisfies the rule. Two strategies are available:
+
+- **Use semantic version** (default): packages are ranked by their version string using SemVer comparison. Use this when your package versions follow SemVer (e.g. `2.1.0`, `2.1.0-beta.3`). The version range and pre-release tag fields described above apply.
+- **Use most recently published**: packages are ranked by the publish date that the feed reports. The version that was uploaded most recently is treated as the latest. Use this when your version strings don't reflect recency — for example, feature-branch tags like `feature-checkout-04`, build numbers like `build-1234`, or date-stamps like `2026-05-29-nightly`.
+
+When **Use most recently published** is selected the version range and pre-release tag fields are replaced by a single **Version tag regex** field — see the next section for details.
+
+#### Most recently published rules {#most-recently-published-rules}
+
+When **Use most recently published** is selected:
+
+1. (Optional) Enter a regular expression in the **Version tag regex** field. This is matched against the **full version string** (not just the pre-release component) and filters candidate versions. Leave blank to consider every version published to the feed. Examples:
+
+    | **Pattern** | **Description** | **Example use-case** |
+    | --- | --- | --- |
+    | (empty) | Matches any version | Take the absolute newest publish, regardless of name |
+    | `^build-\d+$` | Matches versions like `build-1234` | CI build numbers |
+    | `^feature-checkout-.*` | Matches feature-branch tags for one feature | Auto-deploy a specific feature branch to a preview environment |
+    | `^\d{4}-\d{2}-\d{2}` | Matches a date prefix like `2026-05-29` | Date-stamped nightly builds |
+    | `^v\d+\.\d+\.\d+(-\w+)?$` | Matches a SemVer-like shape | Restrict to SemVer-shaped tags while still ordering by publish date |
+
+2. Click **Save**.
+
+The **Design rule** dialog isn't available for Most recently published rules — there's no SemVer range to evaluate candidates against. The regex filter determines which candidates qualify; Octopus then picks the candidate with the latest publish date. When two candidates share the same publish timestamp (a rare tie), the SemVer-higher version wins as a deterministic secondary sort.
+
+:::div{.hint}
+**Feed support.** Most recently published ordering needs the feed to report a publish date per version. It is supported on the built-in NuGet feed, external HTTP and filesystem NuGet feeds, Amazon S3, Google Cloud Storage, Helm, NPM, PyPI, and Artifactory Generic feeds. It is **not** supported on container or OCI registry feeds (Docker, DockerHub, GitHub Container Registry, Amazon ECR, Google GCR, or any OCI registry) because their tag-listing APIs return tag names only — fetching per-tag dates would require an extra manifest call for every tag. When you choose Most recently published for a step that targets one of these feeds, the channel rule editor warns you.
+
+Other feeds that don't report a publish date — including Maven and GitHub feeds — don't error, but they can't order by publish date either: they silently fall back to version-string ordering. Only use Most recently published with the feed types listed above.
+:::
 
 ### Git protection rules {#git-protection-rules}