[object Object]

Patches and upgrades both ship managed solution changes to production. They behave very differently after import, and choosing wrong creates either bloat or downtime.

The mental model

A patch is an additive layer on top of a parent solution. It contains only the components you added to the patch. Multiple patches stack. The runtime computes the effective component set by merging patches over the parent.

An upgrade replaces the parent solution wholesale. Components missing from the upgrade are deleted from the target environment. The deletion phase is what makes upgrades risky and slow.

When patches win

Use patches for incremental changes shipped on a fast cadence:

  • A new optional column added to a table
  • A new ribbon button
  • A bug fix in a single web resource
  • A plugin step registration

Patches are fast to import, fast to roll back (uninstall the patch), and produce minimal layer churn. A team shipping weekly should use patches by default.

The trade-off: the parent solution accumulates patches. After 10 to 15 patches, ALM hygiene degrades; dependencies between patches get tangled, and uninstalling becomes risky.

When upgrades win

Use upgrades when:

  • You are removing components, not just adding
  • The parent has accumulated 10+ patches
  • You are renaming or restructuring components
  • You need a clean baseline for the next quarter

Upgrades give you a single new managed layer that replaces the parent + all patches. Storage and metadata caches get a reset.

The trade-off: longer import (10x to 50x slower than a patch), brief metadata cache invalidation, and any unmanaged changes in production that were dependencies of removed components will fail.

Mechanics that bite

A few things teams learn the hard way:

  • You cannot create a patch on a solution you imported as managed. The patch must be authored in the same dev environment that owns the parent.
  • “Clone a solution” in the maker portal converts patches into a single new parent. Use this before shipping an upgrade if the chain has grown.
  • Apply Solution Upgrade is not automatic. After import as upgrade, you must call DeleteAndPromoteRequest to flip the staging layer to active. Pipelines often miss this step.
  • Plugin steps registered against a removed component are orphaned, not deleted. Clean up via the Plugin Registration Tool.

A practical cadence

Most teams land on this rhythm:

  • Weekly: patches for additive features and bug fixes
  • Monthly: review patch count per solution
  • Quarterly: clone-to-parent and ship as an upgrade in the next maintenance window
  • Annually: review managed solution boundaries and consolidate

Automate the choice

In your pipeline, add a check: if patch count for a solution is greater than eight, fail the build with a message instructing the engineer to roll patches into a parent. This forces hygiene without manual policing.

What to do this week: count patches on your top three production solutions. Anything above eight goes onto next quarter’s upgrade list, with a target maintenance window picked now.

[object Object]
Share