PSA: Getting ready for extension-upgrades

TLDR: Site-builders who manage CiviCRM extensions in the web UI should install the Hotfix: Extension Upgrades. Similarly, site-builders who use cv CLI to download extensions should update to v0.3.63+.

Motivation

The general aim is to make extension-upgrades more reliable -- when you download an extension, you want the download to succeed.

But why do we need a change? We can view this from two angles: the immediate motivation and the structural issue.

• As an immediate consideration, extensions are converting from "Entity Framework v1" (EFv1) to "Entity Framework v2" (EFv2). Both designs have been tested on many versions of CiviCRM. However, at the moment when a site-builder downloads the converted extension, the upgrade may initially fail. The rollout of EFv2 will make this kind of failure more common.
• The underlying problem is not in EFv2. Similar failures affect other extension-upgrades. In fact, the problem originates circa CiviCRM v4.1-4.2. But the symptoms are intermittent -- and if you don't have a reliable diagnosis, then the symptoms appear chaotic. (The problem presents disparate error-messages on unrelated extensions, but only for some users.)
• The real problem lies in the built-in extension-downloader -- which needs to do a better job of unloading old PHP code before it can use new PHP code. The problem appears intermittent because:
  1. Upgrades don't often change the PHP code in a way that provokes a substantive conflict.
  2. When there is a conflict, it is often easier to work-around by clearing caches (rather than submitting a detailed bug-report or patch).
  3. When developers do pre-release testing of their own extensions, they typically don't use the built-in downloader. (It is easier to download pre-releases with git, but this is immune to the problem.)

The recommendation here is to update the built-in downloader -- so that EFv2 conversions (and other upgrades) will work more reliably.

Solutions

The exact solutions will depend on how you manage downloads (and the version of CiviCRM):

• Web-Based Downloads (CiviCRM 6.1+): You do not need to do anything. The web-based downloader is fixed in v6.1.
• Web-Based Downloads (CiviCRM 5.45-6.0): You should install the hotfix for extension-upgrades:
  1. Navigate to "Administer > System Settings > Extensions"
  2. Open the "Add New" tab
  3. Find the item "Hotfix: Extension upgrade"
  4. Download and install it
• CLI Downloads (cv): Ensure that you have cv 0.3.63+. It shouldn't matter which version of CiviCRM you use.
  • Tip: The output of cv dl will look slightly different, because the download process now runs as several sub-steps. It will display a progress-indicator with .... For more detailed progress, enable verbose flags like -v or -vv.
• CLI Downloads (other): If you manually download extensions with git, wget, curl, or some other external tool, then you're not affected.

More information