gistfile1.js

// Currently going to latest.civicrm.org/stable.php outputs:
4.5.2

// Proposed new output (B)
[
  {version: "4.4.0"},
  {version: "4.4.1"},
  {version: "4.4.2", security: true}
  {version: "4.5.0"},
  {version: "4.5.1"},
  {version: "4.5.2", security: true}
  ...
]

// Proposed new layout (C)
[
  "4.4": [
    {version: "4.4.0"},
    {version: "4.4.1"},
    {version: "4.4.2", security: true}
  },
  "4.5":
    {version: "4.5.0"},
    {version: "4.5.1"},
    {version: "4.5.2", security: true}
  ]
  ...
]

I like the branch-name-as-key in theory, but there is some difficulty with the fact that a packaged civi tarball has no way of knowing exactly what branch it was derived from.

PHP version_compare will evaluate something like 4.5.1 as being ahead of 4.5, so that could be used to walk the array of major versions before getting into the minor ones, so long as they're presented in descending order (which seems reasonable). The only hiccup might be that 4.5.beta1 evaluates as below 4.5, so there would need to be some way of dealing with alphas, betas, and so forth--though presumably that could be fine spit out something like "You're on a beta. FYI the newest stable release is 4.5.4."

Well as long as we never deviate from the pattern release x.y.z derives from branch x.y then it's very straightforward, just truncate the string from a packaged release and you've got the branch. So far we've always followed that pattern, don't know why we ever wouldn't.

Regarding expressions like "4.4" or "4.5", I would describe these as MajorVersions -- which are qualitatively different from MinorVersions or BranchNames. You can determine a MajorVersion by parsing the MinorVersion, e.g.

function parseVersion($minorVersion) {
  list($a,$b,$c) = explode('.', $minorVersion);
  $majorVersion = "$a.$b";
  $isStable = is_numeric($c);
  return array($minorVersion,$majorVersion,$isStable);
}

Once you know $minorVersion, $majorVersion, and $isStable for the local installation, it should be pretty easy to walk the version list and figure out:

• Within the same MajorVersion, what's the highest MinorVersion? Do any intermediate releases have the "security" flag?
• Overall, what's the highest MinorVersion? (Optionally filter to match stability requirement)

Edge-case: If you're running the highest MinorVersion in an end-of-life MajorVersion (e.g 4.1.6), it's impossible to determine from this data if you suffer a known security issue... there may be a newer security release (e.g. 4.2.5), but that security issue could have been contemporaneously backported (4.1.5) or could be irrelevant to 4.1. We should probably deal with EOL explicitly -- if your MajorVersion is EOL, then display another warning.

Cool, this spec is shaping up nicely, thanks for thinking around the edge cases.

One question: When would we ever want the majorVersion to be different than the branchName? Seems to make everything easier if they are always exactly the same, and so far they always have been afaik.

Another thought: what if we also include a datestamp for each release in the json? Seems like a generally useful thing to have, but my specific reason for including it is that you could compare the dates of security releases to find out if there is a more recent security release on a later majorVersion, which would mostly tell you if your older version is still secure (it wouldn't account for security issues that only affect later versions, but at least that means it errs on the side of caution). A fully comprehensive solution, if we want to go there, would be to also include an array of versions affected by a security release, like:

{
  "4.4": [
    {version: "4.4.0", date: "2013-01-02"},
    {version: "4.4.1", date: "2013-02-03"},
    {version: "4.4.2", date: "2013-03-04", security: true, affects: ["4.1", "4.2", "4.3", "4.4.0", "4.4.1"]}
  ]
  ...
}

Agree that it's a good convention for BranchNames to match MajorVersions - and we can usually speak of them interchangably. There are cases where they don't match (e.g. "master" vs "4.6" at time of writing) or where matching would be nonsensical (e.g. "master-civimail-abtest" is a long-running feature-branch). It's conceivable that we could change SCM software (svn/bzr/hg/etc) or SCM-conventions (git-flow,etc). Regardless of what happens to SCM, though, we would still speak about releases using MajorVersions and MinorVersions. From the perspective of a client deciding whether to upgrade, it only needs to understand version#s -- not SCM.

+1 for including the release-dates.

-1 for the comprehensive solution (for the moment). I think it would be nice to publish more detailed info about version#s and SAs, but processing that requires more work at every level (spec + publishing + consuming; upfront + ongoing). Publishing version#s and dates is a good bite-sized project (for the moment).

Let's move further discussion to https://issues.civicrm.org/jira/browse/CRM-13672 since gist doesn't support email notifications.