Do not show patch version in Orb Quick Start Guide

Ecosystem Orbs
1

Has Circle considered removing the patch version number from the Orb Quick Start Guide section at the top of every orb page in the orb registry? I suspect pinning to the latest major.minor release would be preferable for more users.

I’ve also noticed a number of Circle’s own orbs show “ORB_NAME@x.y” rather than “ORB_NAME@x.y.z” in their usage examples. Perhaps this is because they also feel pinning to the major.minor release is more widely desirable.

2

Hello @mcafaro,

While we do (as orb authors) somewhat agree that pinning to the minor version may be preferred, the safest option as a user is to pin to a specific patch version. We at CircleCI try our best to follow semver strictly, but not all orb authors follow semver closely or may not even be fully aware of the concept.

From a user standpoint it will always be safest to lock down your version to protect yourself against unwanted changes, but of course the option is always available.

3

Hi @KyleTryon,

Thanks for the response. While I agree that pinning to the patch version is theoretically the safest default, I suspect many less experienced users simply push “Copy This Code” without understanding the ramifications. Those users won’t receive bug fixes without explicitly modifying their YAML.

I would argue that if the orb developer is practicing semver properly, the end user should not be concerned with the particular patch version they are using (or even the minor version). In fact they should always want the latest patch version given that it will include the most bug fixes. A patch release (in theory) should not break a build. I see your point though that all devs may not be as strict about following semver.

I think another point to consider is that many orbs call out to external services (e.g. to download or upload files), so they are not really super self-contained units. In these cases, even pinning to a patch version won’t guarantee things don’t shift on you. I think you’re actually better off not pinning to a patch so the dev can fix things if the external service begins to fail.

Best,
Mark