Option for or default to using max_stable_version when fetching crate info

[zeeshanlakhani]

Are you experiencing an issue with...

shields.io

🐞 Description

A Rust project I've contributed to, called ucan (and ucan-key-support), recently transitioned from (higher-versioned) alpha releases to a stable 0.1.0 release. However, the badge is not getting updated (https://img.shields.io/crates/v/ucan.svg), as it uses the max_version, per this line of code: https://github.com/badges/shields/blob/master/services/crates/crates-version.service.js#L22. In viewing the crate information via https://crates.io/api/v1/crates/ucan, should it use the max_stable_version if it exists, defaulting to max_version otherwise? Here's what the crate data returns:

{
   "crate":{
      "badges":[],
      "categories":[
         "web-programming",
         "cryptography",
         "encoding"
      ],
      "created_at":"2022-03-11T05:26:14.291552+00:00",
      "description":"Implement UCAN-based authorization with conciseness and ease!",
      "documentation":"https://docs.rs/ucan",
      "downloads":1875,
      "exact_match":false,
      "homepage":"https://github.com/cdata/rs-ucan",
      "id":"ucan",
      "keywords":[
         "jwt",
         "ucan",
         "pki",
         "authz"
      ],
      "links":{
         "owner_team":"/api/v1/crates/ucan/owner_team",
         "owner_user":"/api/v1/crates/ucan/owner_user",
         "owners":"/api/v1/crates/ucan/owners",
         "reverse_dependencies":"/api/v1/crates/ucan/reverse_dependencies",
         "version_downloads":"/api/v1/crates/ucan/downloads",
         "versions":null
      },
      "max_stable_version":"0.1.0",
      "max_version":"0.7.0-alpha.1",
      "name":"ucan",
      "newest_version":"0.1.0",
      "recent_downloads":1032,
      "repository":"https://github.com/cdata/rs-ucan/",
      "updated_at":"2022-11-29T18:39:54.791532+00:00",
      "versions":[
         634470,
         552070,
         525823,
         525094,
         520718,
         519720,
         517394,
         517384,
         514425,
         514412,
         673114
      ]
   }
}

🔗 Link to the badge

https://img.shields.io/crates/v/ucan.svg
https://img.shields.io/crates/v/ucan-key-support.svg

💡 Possible Solution

No response

[chris48s]

I'm not necessarily opposed to this - showing stable versions in preference to unstable is our usual behaviour for version badges - but I'd like to understand more first. By normal semver rules both 0.1.0 and 0.7.0-alpha.1 would both be considered 'unstable'

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

Where we have only unstable releases to choose from, we'd usually pick the numerically latest one.

I can't seem to find any docs for it, but how does max_stable_version work? Is it entirely user-determined? Does the rust ecosystem have some concept of "some unstable versions are more stable than others"?

I'm trying to avoid specifically tagging @calebcartwright into things, but this specific issue might be a good one for you to weigh in on.

[zeeshanlakhani]

@chris48s thanks for taking a gander. So, on crates.io, e.g. https://crates.io/crates/ucan/versions, 0.1.0 is considered stable and not a prerelease (which alpha dictates). It's really stable vs prerelease otherwise. In crates code, max_stable_version is what they actually use as the default version: https://github.com/rust-lang/crates.io/blob/master/app/models/crate.js#L35, if it exists. They calculate it like so with the prerelease check:

hash.max_stable_version = versionNums.find(it => !prerelease(it, { loose: true })) ?? null;

[zeeshanlakhani]

@chris48s, additionally, I think this note hints that crates have moved off max_version directly ~ https://github.com/rust-lang/crates.io/blob/20bbac9f5521cb4888ef63f8464fddb28fd973f5/src/views.rs#L214.

[calebcartwright]

There's been some increased chatter this year on both internals and rfcs/cargo in the Rust ecosystem around some of the nuance and challenges of semver handling, particularly with prerelease versions.

I assume that's indeed being reflected in the different values within the api response we're seeing given the inherently necessary coupling between cargo and crates, and that we should indeed utilize max_stable_version. Will double check with the crates team to confirm though