Reframe upgrade messaging
This issue started as a discussion in Mattermost. The opening summary/statement is captured below
Before I can speak fluidly about this, we should cover some background material so that we have common concepts/terms.
- If you talked to a dozen people, you'd find that organic day-to-day use of terms like "major", "minor", "release", "version", "branch", "tag", and "upgrade" is not entirely consistent. The SemVer specification tries to standardize some of these words: a version number (
5.6.7) is decomposed as
- In Civi v4.6/v4.7, the logic+prose for upgrade-messaging was hard-coded into the app. With the introduction of 5.x, we moved the messaging logic to a backend service (civicrm-pingback) so that we could be more responsive/iterative in adjusting the messages.
- On a specific site at a specific time, the admin may see up-to two messages. These messages convey different information which resonates (or not) in different ways:
upgrademessage informs about the status of the
MAJOR.MINOR(e.g. if you're on v5.5, you might see a prompt about upgrading to v5.9).
patchmessage informs about the status of the
MAJOR.MINOR.PATCH(e.g. if you're on v5.5.1, you might see a prompt about upgrading to v5.5.3).
- It can be hard to grok all the ways in which these messages are presented to different folks. Use the
devPreviewto get a visual:
- Every status message displayed in CiviCRM has a brief
title, an optional/longer
info), and an internal/hidden
name(for tracking purposes). The icon+coloring are dictated by the
- Within the backend service, messages are generated with SummaryReport.php and versions.json.
versions.jsonfile basically tracks the dates and statuses of each "MAJOR.MINOR" (
5.7, etc) and each "MAJOR.MINOR.PATCH" (
MAJOR.MINORmay have a
schedule. The schedule automatically overrides the status. (This was a recent change. In previous months, the
statusinfo would grow stale; we added the
scheduleto make it easier to maintain accurately.)
(Note: This has already grown a bit long; I'll post the more opinionated thoughts in a follow-up comment.)