Rewriting branching and hotfix patterns sections by BobJWalker · Pull Request #3420 · OctopusDeploy/docs

BobJWalker · 2026-08-25T22:09:37Z

This pull request:

Rewrites the branching patterns page to reflect Octopus from 2026, not Octopus from 2016
Removes old v3 era images of Octopus Deploy that was used by the branching patterns page.
Replaces the hotfix example in the lifecycles page with the recommend release lifecycle

Removing old v3 images of Octopus Deploy. Removing hotfix example in lifecycles page.

team-marketing-branch-protections · 2026-08-25T22:26:48Z

Pull request environment is available at https://stoctodocspr3420.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.

mattallford

Great work, Bob. Thanks for doing this, it definitely removed some very outdated information from our docs.

1 thing to look at across the board - and again is minor - is that at times you have capitolized environments (like Production, Test), and sometimes they are lower case. It's minor, but maybe a "Find and replace" to make it consistent (just need to keep an eye out for when a sentence starts with an environment name)? Looking at our grammar rules, I feel like environment names should be lower case by default.

mattallford · 2026-08-25T23:42:28Z

+### Different deployment process per branch

-Normally in Octopus, a single release for a project is deployed to a single environment at a time - for example, only one release is "currently" in Production. When you have multiple active release branches, or sometimes even feature branches, it might be that you actually have more than one "current" release.
+Sometimes a new feature introduces a new component requiring a change to the deployment process.  All projects should use [version control](/docs/projects/version-control), or the config-as-code feature.  That stores the deployment process, runbooks, variables, and deployment settings in a git repo.  


You told me off for using "config-as-code" in our Octopus fundamentals certification :) I actually recently edited the certification to use "Project version control", but my worry was that our docs still refer to "Configuration as code". Just flagging it here.

Also, the way it's written here might suggest version control and config-as-code are two different things, and projects should use one or the other.

Updated to config as code to be consistent

mattallford · 2026-08-25T23:45:52Z

- The stable channel is deployed to the same web servers as the Early Adopter channel, but each goes to a different IIS website.
- The stable channel and Early Adopter channels go to different web servers.
- Each feature branch goes to its own virtual directory.
+Store the Octopus Deploy configuration in the same repository as the source code.  Often a change to the deployment process has a corresponding code change.  By leveraging project version control, both code and deployment changes are made in a branch and merged in the same pull request.


Swap "leveraging" for "using" (Octopus Grammar rules).

mattallford · 2026-08-25T23:50:59Z

-:::figure
-![Variables scoped to the Early Adopter channel](/docs/img/deployments/patterns/images/3278474.png)
-:::
+- **Default:** Development Only


Change "Only" to have lowercase o

mattallford · 2026-08-25T23:53:25Z

-:::
+1. Create a channel for each possible combination of components.  One channel for web front-end and API back-end, another channel for API back-end and database, another for the backend service and database.  Scope appropriate steps to each channel.
+2. Create a project for each component and a orchestration project.  The orchestration project skips component unchanged component projects.
+3. Have a single deployment process, but leverage [script steps](/docs/deployments/custom-scripts), [output variables](/docs/projects/variables/output-variables), and [variable run conditions](/docs/projects/steps/conditions/#variable-expressions) to skip unnecessary steps.  The script steps run on the deployment targets and pre-check for version differences.


Change "leverage" to "use"

mattallford · 2026-08-25T23:59:33Z

+
+**Disclaimer:**- Include all static testing environments in the Release lifecycle required to reach Production.  If only Test &rarr; Production are required, then only include two environments.  Never include the Development environment.  Development is for testing changes from branches.
+
+The **Default** lifecycle represents unfinished work in a branch.  The **Release** lifecycle represents the main or primary branch.  Unfinished work should never have a path to Production.  For more information please see the [branching in Octopus Deploy](/docs/deployments/patterns/branching).


Remove "the" before the link to branching.

mattallford · 2026-08-26T00:06:20Z

+- **Default:** Development Only
+- **Release:** Test &rarr; Staging &rarr; Production
+
+**Disclaimer:**- Include all static testing environments in the Release lifecycle required to reach Production.  If only Test &rarr; Production are required, then only include two environments.  Never include the Development environment.  Development is for testing changes from branches.


Remove hyphen after Disclaimer:

mattallford · 2026-08-26T00:06:44Z

+- **Release:** Test &rarr; Staging &rarr; Production

-Modeling this in Octopus is a little more complicated than the scenarios above, but still easy to achieve. If the only thing that changes between branches is the NuGet package version numbers, and you create releases infrequently, then you can simply choose the correct package versions when creating a release via the release creation page:
+**Disclaimer:**- Include all static testing environments in the Release lifecycle required to reach Production.  If only Test &rarr; Production are required, then only include two environments.  Never include the Development environment.  Development is for testing changes from branches.


Remove hyphen after Disclaimer:

BobJWalker added 2 commits August 25, 2026 16:53

Rewriting the branching patterns page to reflect 2026 Octopus Deploy.

ef86b6a

Removing old v3 images of Octopus Deploy. Removing hotfix example in lifecycles page.

Webp and png generated images

2621cd2

BobJWalker requested a review from mattallford August 25, 2026 22:09

Fixing the linting problems

0b91c35

mattallford reviewed Aug 26, 2026

View reviewed changes

Line edits based on PR comments

9fad1dd


		Disclaimer:- Include all static testing environments in the Release lifecycle required to reach Production. If only Test → Production are required, then only include two environments. Never include the Development environment. Development is for testing changes from branches.

		The Default lifecycle represents unfinished work in a branch. The Release lifecycle represents the main or primary branch. Unfinished work should never have a path to Production. For more information please see the [branching in Octopus Deploy](/docs/deployments/patterns/branching).

Uh oh!

Conversation

BobJWalker commented Aug 25, 2026

Uh oh!

team-marketing-branch-protections commented Aug 25, 2026

Uh oh!

mattallford left a comment

Choose a reason for hiding this comment

Uh oh!

mattallford Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mattallford Aug 25, 2026 •

edited

Loading