Document non-SemVer package ordering on channel package version rules#3191
Merged
Conversation
7637a7a to
6d48063
Compare
Contributor
Author
|
Blocked by https://github.com/OctopusDeploy/OctopusDeploy/pull/43780 being reviewed |
|
Pull request environment is available at https://stoctodocspr3191.z22.web.core.windows.net. You can view the ephemeral environment status in Octopus Deploy. This environment will be automatically deprovisioned when the pull request is closed, or after 7 days of inactivity. |
541d0e2 to
a0dfffb
Compare
Contributor
Author
Corrections after cross-checking against implementation PR #43750Verified the docs against the merged server implementation and pushed a fix (e57aba5):
Claims that checked out and were left unchanged: regex matched against the full version string, SemVer-higher tie-break as the secondary sort, container/OCI unsupported set, and the Design Rule dialog being disabled under MRP. |
Adds documentation for the new "Most recently published" ordering strategy and version tag regex on Channel Package Version Rules — a feature that lets channels rank package versions by publish date instead of SemVer comparison, enabling feed triggers and release creation to work with non-SemVer schemes like feature-branch tags, build numbers, and date-stamped builds. Primary change: - releases/channels/index.md: expanded the Package version rules section to introduce the Ordering strategy choice (Semantic version / Most recently published) at step 3 of rule creation. Added a "Most recently published rules" subsection with a regex examples table and a callout listing supported and unsupported feed types. Cross-references: - projects/project-triggers/external-feed-triggers.md: expanded the troubleshooting note that previously said the trigger evaluator only uses SemVer to point at the new MRP option, with a note on unsupported container/OCI feeds. - packaging-applications/create-packages/versioning.md: added a one-line pointer under "Choosing a versioning scheme" for users whose toolchain produces non-SemVer version strings. Related: OctopusDeploy/OctopusDeploy PR #43780 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
CI runs markdownlint-cli2 only on files changed by the PR, so the prior commit's single-sentence addition to versioning.md surfaced 23 long- standing violations in the same file that had been latent on main. Fixed mechanically: - MD029 (ordered-list prefix): continuation paragraphs under list items 1, 3, 4 were indented 2 spaces instead of 3, breaking them out of the list and making each subsequent item look like a fresh "1." Indented to 3 spaces so the list stays connected. - MD005 (list-indent): item " 3." in the "How Octopus Deploy treats semantic versions" list had a stray leading space. - MD004 (ul-style): two unordered lists under "Maven versions" used `*` bullets; the repo style is `-`. - MD007 (ul-indent): "Learn more" list items were indented one space; should be column 0. No content changes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
GitHub feeds don't implement publish-date ordering, so remove them from the supported list. Add a note that feeds without publish dates (Maven, GitHub) silently fall back to version ordering, and that the strategy is gated behind the non-semver-ordering feature toggle. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
e57aba5 to
8b5d3bf
Compare
liam-mackie
approved these changes
Jul 16, 2026
liam-mackie
left a comment
Contributor
There was a problem hiding this comment.
This is better than what we had, but there are some changes I'd love if you took a look through and actioned before merging.
| 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. |
Contributor
There was a problem hiding this comment.
Nit: maybe we should mention that it is available on GCR feeds, and not the generic OCI feeds?
| #### 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. |
Contributor
There was a problem hiding this comment.
Nit: we should probably just push the ordering live rather than mention our internal feature toggling behavior. A release version would be good?
| | `^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 | |
Contributor
There was a problem hiding this comment.
I don't like having this Semver-like shape. We should probably remove this one.
|
|
||
| 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. |
Contributor
There was a problem hiding this comment.
Nit: Do we use SemVer-higher version, or is it literally alphabetically ordered?
| 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. |
Contributor
There was a problem hiding this comment.
Nit: consider a table for feed support
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds public docs for the new Most recently published ordering strategy and Version tag regex field on Channel Package Version Rules — a feature implemented in OctopusDeploy/OctopusDeploy PR #43750 that lets channels rank package versions by publish date instead of SemVer comparison.
This enables feed triggers and release creation to work with non-SemVer schemes like feature-branch tags (
feature-checkout-04), CI build numbers (build-1234), and date-stamped names (2026-05-29-nightly).Details
Expanded the Package version rules section to introduce the Ordering strategy choice (Use semantic version / Use most recently published) at step 3 of rule creation. Added a new Most recently published rules subsection with:
Expanded the troubleshooting line that previously said "The trigger's version evaluator uses SemVer" into a paragraph that points at the new MRP option, with the unsupported-feed caveat.
Tip for: Choosing a versioning scheme for users whose toolchain produces non-SemVer version strings.
🤖 Generated with Claude Code