[question] best practices for versioning extensions

[talss89]

Hello! I've built a bud extension, and would really value some advice on how to tag / package versions to maintain compatibility with bud.

Ideally, I would like the package to be compatible with bud upgrade - which AFAIK means tracking the @roots/bud release.

This is fine, but I can see that creating a bit of friction between bud and 3rd party extensions. Say bud is at 6.16.1, but the 3rd party needs to release an update to their existing 6.16.1-compatible release, they will (unless I've overlooked something) need to unpublish / republish the package 😬, or wait until bud 6.16.2.

I did wonder about using hyphen pre-releases (ie. 6.16.1-2), but that a) negates the benefits of semver for the 3rd party extension, and b) requires that the intial release is tagged with a hyphen, as non-pre-release versions take priority over hyphenated pre-releases.

If we flipped the above around - ie. 1.0.1-6.16.1, we may be able to avoid a), but I think that'd require a change to bud upgrade.

I'm probably overlooking a simple solution.

[kellymears]

This is uncharted territory. I do think there will need to be a change to bud upgrade, ultimately.

Unsure how to approach it yet. One idea is a bud field in package.json for extensions, like:

{
  "name": "my-extension",
  "version": "1.0.1",
  "bud": {
    "version": "6.16"
  }
}

I like this because the package maintainer can independently version their code. I think bud.js is in a place now where there is no need for packages to release updates just because we did. I also don't think this is maintainable or appealing for extension maintainers.

My initial thinking:

When a user running 6.16.1 runs the upgrade command, bud.js:

• Scans the user package.json for bud- packages outside the @roots namespace
• For each matching package, we request the releases using npmjs.com API
• Starting with the most recent release we request info until we find something that fulfills the semver requirements.
• bud.js upgrades the package to that version.

The unresolved question:

• What do we do when there is no installation candidate?

[talss89]

Yeah, I really like this idea. Having the ability for an extension to target a range of bud releases is ideal. +1 for your approach.

As for what we do when there is no installation candidate: I ran bud upgrade against my package, and was presented with this:

@talss89 ➜ /workspaces/sandbox $ yarn bud upgrade
yarn run v1.22.19
$ /workspaces/sandbox/node_modules/.bin/bud upgrade
[1/5] Validating package.json...
[2/5] Resolving packages...
Couldn't find any versions for "bud-embedded" that matches "6.16.1"
? Please choose a version of "bud-embedded" from this list: (Use arrow keys)
❯ 0.0.10 
  0.0.9 
  0.0.8 
  0.0.6 
  0.0.5 
  0.0.4 
  0.0.3 
  0.0.2 
  0.0.1 
  0.0.0 

I quite like that, too.

[kellymears]

@talss89 I saw you did a bump on bud-localtunnel which includes the new bud.version field. That's great.

nightly seems to be working.. using this package.json:

{
  ...
  "devDependencies": {
    "@roots/bud": "nightly",
    "@roots/bud-tailwindcss": "nightly",
    "@roots/sage": "nightly",
    "bud-localtunnel": "0.0.1"
  }
}

yarn bud upgrade 6.16.0:

[project] [hooks] › set package manager to yarn
[project] [hooks] › { required: '>=6.16.0', satisfies: true, version: '6.16.0' }
[project] [hooks] › Upgrading devDependencies
 @roots/bud@6.16.0
 @roots/bud-tailwindcss@6.16.0
 @roots/sage@6.16.0
 bud-localtunnel@0.0.2

{
  ...
  "devDependencies": {
    "@roots/bud": "6.16.0",
    "@roots/bud-tailwindcss": "6.16.0",
    "@roots/sage": "6.16.0",
    "bud-localtunnel": "0.0.2"
  }
}

Running yarn bud upgrade 6.15.0 (which does not match) defaults to latest and ultimately resolves to ^0.0.2 (note the ^), as intended:

[project] [hooks] › { required: '>=6.16.0', satisfies: false, version: '6.15.0' }
[project] [hooks] › Upgrading devDependencies
 @roots/bud@6.15.0
 @roots/bud-tailwindcss@6.15.0
 @roots/sage@6.15.0
 bud-localtunnel@latest

{
  ...
  "devDependencies": {
    "@roots/bud": "6.15.0",
    "@roots/bud-tailwindcss": "6.15.0",
    "@roots/sage": "6.15.0",
    "bud-localtunnel": "^0.0.2"
  }
}

The logging leaves a bit to be desired and we should warn when a package doesn't have a match.. but overall it seems to be working.

I'll cut a 6.17.0 release; we can patch things as needed from there.

[talss89]

Awesome! Looks good to me.

Just tested nightly against bud-wp-editor-query, and that's worked exactly as expected too.

Sounds like a plan re. logging for ^16.17.1.

[kellymears]

OK, I lied. I'm going to merge this and do one last nightly. I think it's a better experience, overall.

#2464

[kellymears]

Seems good to me!