Docs update: Releases with extra version info (e.g., 1.1.0-alpha1, -beta2, etc.) are not recommended

[bugfolder]

This is not necessarily a bug, but it came up in This Zulip chat about the Paragraphs module. Opening this issue so we can continue the discussion here.

The issue is that the Paragraphs module currently has a version 1.2.0-beta1 and an older version 1.1.0, and the older version is being shown as the "Recommended release."

This choice is baked into the code of the project_release module, in this function:

function project_release_find_latest_releases($project_nid, $version_api, $version_major, $access = FALSE) {
  $latest_release = $recommended_release = $latest_security_release = 0;

  foreach (project_release_query_releases($project_nid, $version_api, $version_major, $access) as $release) {
    if (empty($latest_release)) {
      $latest_release = $release->nid;
    }
    if (empty($recommended_release) && empty($release->project_release['version_extra'])) {
      $recommended_release = $release->nid;
    }
    if (empty($latest_security_release) && project_release_is_security_update($release)) {
      $latest_security_release = $release->nid;
    }
...

Any release that has version_extra information (like alpha1,, beta1, etc.) will not get assigned as the $recommended_release.

[bugfolder]

This should be documented on https://docs.backdropcms.org/documentation/contribute-to-a-module-layout-or-theme.

[jenlampton]

I think all the release information should be removed from that page, actually, and added to
https://docs.backdropcms.org/documentation/maintaining-a-contributed-project

With it in two places, it could become easy to have conflicting information.

edit: should we move this issue to the docs queue?