Use Semver in version strings

[ghost]

Hey, thanks for creating & maintaining this repo! It's exactly what I was looking for, and the recommended architecture the project defaults to is very interesting! This is minor, but the date-identified versions of the userscripts aren't valid semver. While it's not perfect, I think it'd be better to add the date as build metadata as per https://semver.org/, i.e. delimited by a plus at the beginning, and then ASCII alphanum hyphen. Again, not hugely important, but why deviate from a spec when one exists.

Cheers!

[ghost]

I just realized that of course while the default version in userscript.ts is semver, no one is forcing authors to use semver, so that might not even matter to most people. So an option or way to make the generated version semver-conformant is also fine with me, if you don't want to impose a policy on this.

[SimonAlling]

Hi @SamuelSwartzberg! Thank you for reaching out about this! 🙂 Sorry for the late reply! 🙏

I've been thinking a lot about versioning and releasing software during the last couple of years. It really is one of those things that are much trickier than one might think. Hyrum's Law comes to mind, but also aspects like automated vs manual releases, making releases as atomic as possible (to avoid e.g. merging and tagging a release that cannot be published/distributed, or vice versa), etc.

Userscripts, I would say, are distinctly different from a typical software package in how they are consumed and what a "release" means. Most npm packages, for example, have an API that the user consumes, and the user can upgrade whenever they want. The "API" of a userscript differs from such an API in two important ways:

• It doesn't face its user, but the host site, which can be changed at any time, breaking the userscript.
• It is reversed, in the sense that a userscript consumes the host site; no one really consumes the userscript.

So it's typically the userscript author that needs to react to changes in the host site, not the userscript user that needs to react to changes in the userscript. And it often makes no sense for a user to stick to an old version of a userscript, because it will have been broken by the host site.

Therefore, I abandoned any attempts to use SemVer in favor of a more SAAS-like approach in Better SweClockers (for which I originally created Userscripter) in SimonAlling/better-sweclockers#134. I feel like Userscripter should probably follow suit and generate/suggest/default to versions like 2024.7.17+114740 or similar, but maybe there are reasons not to do so?

Now, this discussion does beg an interesting question: should a userscript author be able to and/or try to distinguish between releases that fix sudden breakage caused by the host site and releases altering the behavior of the userscript itself? If yes, then one should keep in mind that userscript managers like Violentmonkey, unlike package managers like npm, don't seem to assign any SemVer-like meaning to version strings. If there is a new version, they upgrade to it, whether it's a new "major" or not.

If you never want Userscripter to append anything to your version, then you can do this:

diff --git a/webpack.config.ts b/webpack.config.ts
index 795ce6a..4f3d122 100644
--- a/webpack.config.ts
+++ b/webpack.config.ts
@@ -17,6 +17,11 @@ export default createWebpackConfig({
             id: U.id,
             now: new Date(),
         }),
+        appendDateToVersion: {
+            development: false,
+            nightly: false,
+            production: false,
+        },
         sassVariables: { CONFIG, SITE },
     },
     metadata: METADATA,

What versioning strategy do you use in your userscripts, and what are your thoughts on this? 🙂

[ghost]

Those are very good points, and some of my thinking on this issue has evolved significantly since I added this issue as well. Versioning is indeed far more complicated than I gave it credit for. I do think there could be a sense in which semver makes sense for userscripts, because while major version increments may be forced, and thus the major version may quickly become quite large (though I've seen the argument that semver properly done should encourage major version changes far more often than is common anyway) and thus generally uninformative (especially since as you mentioned sticking with the old version would also render the site broken, thus doing the exact opposite of what one would expect from not upgrading), semver could still communicate that in fact no breaking changes have occurred, merely features added or bugs fixed if the major version has not changed. Though I agree that is probably of limited utility. A calver-like system would probably be a better fit for the default, I agree. Certainly I have never found the need to properly semver my userscripts, they're all at 0.0.1 - but I'm also the only person using them, so a certain laxity is expected, I guess. :D Since I've generally reduced my usage of userscripts in the meantime, I have no strong need for any particular changes, but I do think calver-like might be the way to go. I'm fine deferring any decision to you, however.

[ghost]

As for the question, that is interesting. Having two different version numbers for the purpose, perhaps one like 'api-level' for reacting to changes to the website (seeing the website's content as a sort of api to whose changes one must react) and one semver for the script itself could be interesting, but given that's not supported by userscript managers, trying to implement that may be a reasonable amount of effort for no real benefit. (though at its simplest, one could have the two numbers and concatenate them somehow in the output version) Perhaps just best to see if there is future demand for such a separation?