[FEATURE] Versioning and automating versioning #468

pww217 · 2022-05-26T21:34:10Z

Is your feature request related to a problem? Please describe.

The decided-upon versioning scheme is calver. To cut our first proper release, we'll need to settle on a final format for each version (ie is it simply YYYY.MM.DD?) and a way to deploy it, ideally with change notes and information for consumers of the build and a list of contributors for each release, if we want.

This issue is to discuss different methods to format versions and handle their release.

Describe the solution you'd like

Once the tagging format is decided on, we just need to work through what steps in the release process need to take place and what should be automated vs manual. This is the process as outlined by Github. We could do anything from a fully-automated release to a hybrid of some manual and some generated release notes.

I'll be doing more research on this over the next week and updating this issue as appropriate.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

pww217 · 2022-06-02T17:17:51Z

Hey @fpliger just let me know what the versioning format will be, and I can do the work to get a release model going somewhat quickly.

Is it YYYY.MM.DD? Is there a major or minor version in there? That's pretty much all I need to know.

josephrocca · 2022-06-12T11:34:59Z

I'm not sure if the ship has sailed on this one, but are you sure that it's a good idea to depart from semver? Every other JS project uses semver, and there is a lot of tooling built around the assumption that packages follow this convention. This, for example, includes security tooling in package managers that help devs detect and manage vulnerable packages. Tools like npm audit (and the equivalent future commands in deno other JS package management tools) will suggest the wrong upgrades to users if calver is used, for example.

Semver also allows package authors to e.g. release a critical security update for the old 2.x.x version despite the fact that the current version of the package is 5.x.x. This allows people that are still using 2.x.x to quickly secure their application without having to upgrade all the way to 5.x.x, which may not be easy. The JS tooling helps people manage this process, and it's made possible by the shared meaning of that leading digit across the whole JS ecosystem.

@fpliger In your reasoning for going with calver, you mentioned this:

An important aspect to keep in mind is that PyScript is still in its very early stages. So, we should highlight that the expectations should be that think can often break until we reach a level of maturity and stability.

For the current state of PyScript (and what I expect it to be in the near foreseeable future), we have a lot to add, change, and remove. It's likely that we will be changing some APIs and something that will require users to change their code. Calver is really a better fit, IMHO.

The usual convention here is to simply start the version number at 0.X.X, and only increment the leading number (to 1.X.X) when you've reached the first stable version. All further increments to the leading number indicate changes that could break a user's code.

Either @sugatoray's hybrid proposal of <Major>.YYYY0M.0D<Micro> or @ryansobol's Major.Year.Month.Day also work as middle grounds - the most important part is that the breaking changes are indicated by the leading digit.

I think the convention is so strong and relied-upon across the ecosystem that there needs to be an extremely strong argument made against at least having a semantic leading digit.

josephrocca · 2022-06-12T11:38:32Z

Regarding this part of this comment:

With all that said, is that the best we can do? No. I think we can do better... and actually make the difference between the versions of PyScript Framework and the specific APIs of the Framework. So, for instance, PyScript version X.Y.Z can support API version 1.2.3 while version X.Y+1.Z can introduce a new API version (let's say 2.0.0) that is intentionally incompatible with the previous (1.x.y) and actually support both (allowing for a deprecation cycle, if necessary). This model is not that uncommon for tools/frameworks with versioned APIS or schemas. PyScript is new. We intentionally have been using alpha only to express "expect things to break" and it'll take time to have a mature and stable API.

I don't really understand - if the user has written some PyScript code, then don't they just care about breaking changes to PyScript? So the "contract" with the user can just be a single version string like X.Y.Z, and everything else is just an internal implementation detail that developer of PyScript itself need to worry about? I could definitely be misunderstanding something here - apologies if so!

fpliger · 2022-06-15T18:02:29Z

@josephrocca , thanks for your feedback here and sorry for the slow reply here... I wanted to make sure the rest of the core team is aligned after the points made in this thread.

I'm not sure if the ship has sailed on this one, but are you sure that it's a good idea to depart from semver? Every other JS project uses semver, and there is a lot of tooling built around the assumption that packages follow this convention. This, for example, includes security tooling in package managers that help devs detect and manage vulnerable packages. Tools like npm audit (and the equivalent future commands in deno other JS package management tools) will suggest the wrong upgrades to users if calver is used, for example.

Semver also allows package authors to e.g. release a critical security update for the old 2.x.x version despite the fact that the current version of the package is 5.x.x. This allows people that are still using 2.x.x to quickly secure their application without having to upgrade all the way to 5.x.x, which may not be easy. The JS tooling helps people manage this process, and it's made possible by the shared meaning of that leading digit across the whole JS ecosystem.

That's sort of an industry problem that should be fixed upstream. The decision of adopting calver is exactly due to that. The promise that semver will tell you if it's safe to upgrade and you tools automating things for you is (too often) a lie and cannot be guaranteed. After years and years in open source software we came to the conclusion that it makes no sense (and we'd not be honest to our users) for us to promise the guarantees of semver. Especially considering where PyScript is today and long road ahead. It makes more sense to us to evaluate other strategies like codenames, blog posts, webinars etc, to denote those generational changes (especially at this point).

In general, we'll always try to keep backwards capabilities and add deprecation cycles when we change API (when possible) but realistically, anyone using PyScript today should understand that it's in Alpha stage. After so many years in the industry, also working closely with package managers, repository and package building teams, I believe that the main overall change tat should happen is fact is that users should always upgrade versions carefully and have tests to make sure upstream new releases don' break their code (from patch to minor and major releases). The discussion and links in # 337 are also relevant

The usual convention here is to simply start the version number at 0.X.X, and only increment the leading number (to 1.X.X) when you've reached the first stable version. All further increments to the leading number indicate changes that could break a user's code.

Either @sugatoray's hybrid proposal of .YYYY0M.0D or @ryansobol's Major.Year.Month.Day also work as middle grounds - the most important part is that the breaking changes are indicated by the leading digit.

I think the convention is so strong and relied-upon across the ecosystem that there needs to be an extremely strong argument made against at least having a semantic leading digit.

Wouldn't that be trying to squeeze semver into calver and make it even more confusing? The problem I see here is the need to for "a stable version" that can allow users to be sure they can upgrade and, as I mentioned earlier, we shouldn't offer that illusion and be honest to ourselves. Users of PyScript today should expect the best effort on our side to not break code and all the efforts we can to socialize when we know code will break but should also not trust version numbers alone and do an effort on their side to test things before upgrading.

As the project matures things might change. PyScript itself will probably change and we can re-evaluate the framework and related tools (including version conventions)

I don't really understand - if the user has written some PyScript code, then don't they just care about breaking changes to PyScript? So the "contract" with the user can just be a single version string like X.Y.Z, and everything else is just an internal implementation detail that developer of PyScript itself need to worry about? I could definitely be misunderstanding something here - apologies if so!

No worries, it's probably a lack of setting the context on my side. This is really me thinking about a possible future development for PyScript components APIs and so... Probably better to keep it on the back burner for now, until we have a good use case.

josephrocca · 2022-06-15T20:34:37Z

I've added some explicit question markers as (1), (2) and (3) in the text below to help organise the key points that I'd love to get answers on, if that's okay!

The promise that semver will tell you if it's safe to upgrade and you tools automating things for you is (too often) a lie and cannot be guaranteed.

should also not trust version numbers alone and do an effort on their side to test things before upgrading.

Such a strong promise is not necessary for the key utility of semver to be realised - "perfection" is not needed, and the automated tools are never used without human supervision. It's simply that having markers for large/likely-breaking changes is useful - and not just for the automation tooling. E.g. this example that I gave in my previous comment:

Semver also allows package authors to e.g. release a critical security update for the old 2.x.x version despite the fact that the current version of the package is 5.x.x.

(1) How does calver handle this sort of thing? It seems like patch/fix releases for older versions would be less legible and harder to manage.

Funadamentally, having major versions forces projects to be respectful of the ecosystem that surrounds the project - breaking changes are generally "saved up" until there are enough for a major version. This allows the ecosystem around PyScript to move "in step" with it much more easily. Things in the ecosystem can target/support a major version of PyScript, and the support matrices (even if not explicit) remain "sane"/manageable.

Breaking a convention incurs a cost that is proportional to the strength of that convention within the ecosystem. The semver convention within the web ecosystem is quite strong! (2) Is there really a strong enough reason to break this convention? If there were strong benefits to using calver, it might be worth it, but what's the strong benefit here? If it's because you need to be nimble in these early stages of the project, why not just stick with 0.X.X (which implies "alpha" by convention) and make as many breaking changes as you need for as long as you're need to?

(3) All listing of versions in package managers / Github releases / etc. have dates beside the version numbers. I.e. users can easily see the date on which any particular version was published. Is there any reason to include this date within the package version itself? Why not use that "real estate" to indicate some useful information about compatibility (again, it doesn't need to be perfect - just best-effort to help ecosystem).

Thanks for taking the time to reply!

fpliger · 2022-06-15T23:14:32Z

(1) How does calver handle this sort of thing? It seems like patch/fix releases for older versions would be less legible and harder to manage.

Given a CalVer number like YYYY.MM.## where ## is a counter, we can just bump the counter for a fix/patch on an older version.

Breaking a convention incurs a cost that is proportional to the strength of that convention within the ecosystem. The semver convention within the web ecosystem is quite strong! (2) Is there really a strong enough reason to break this convention? If there were strong benefits to using calver, it might be worth it, but what's the strong benefit here? If it's because you need to be nimble in these early stages of the project, why not just stick with 0.X.X (which implies "alpha" by convention) and make as many breaking changes as you need for as long as you're need to?

(3) All listing of versions in package managers / Github releases / etc. have dates beside the version numbers. I.e. users can easily see the date on which any particular version was published. Is there any reason to include this date within the package version itself? Why not use that "real estate" to indicate some useful information about compatibility (again, it doesn't need to be perfect - just best-effort to help ecosystem).

[Including both 2 and 3 since I believe they are both addressed below]
We are not breaking the SemVer. We are choosing to adopt a different convention based on the reasons discussed in this and #337. I'll put the post I linked that Issue here as well since I think it's a great resource. In general all of these resources should provide a view into why the maintainers team is choosing CalVer.
Also worth pointing out that PyScript is not the first or the main project choosing to adopt CalVer. Unity, pip, PyCharm, Ubuntu, PyTZ and many others use it.

Overall, I'm sorry this choice may not make everyone happy (definitely a hard goal) but ultimately the maintainers team needs to make decisions based on their experience and what's best. The CalVer proposal had unanimous from all maintainers and many collaborators and the 👍 largely overwhelmed the number of 👎 . For this reason, it's worth a try.

Thanks for the feedback and for taking the time to express your concerns, we really appreciate it. Hope you can understand. 🍻

josephrocca · 2022-06-16T05:21:20Z

Thanks for your reply :) It seems like a bad decision to not at least try to "group" breaking changes and to make those attempts explicit in the version string, and I can't see a strong reason to go against the ecosystem's package convention here, but like you said, it's hard to please everyone. Thanks for patiently responding to my comments - PyScript is an exciting project and I'm rooting for it! 🍻

antocuni · 2022-06-16T07:34:25Z

I agree that being able to deploy security fixes to old releases is critical, but as fabio said YYYY.MM.## already addresses this particular issue.

That said, the main difference between calver and semver is that both introduce breaking changes but semver gives the false security of being able to do upgrades effortlessly, which is most often a false claim for a software of the size of pyscript, at least in my experience. This principle is well explained by the Hyrum's Law:

With a sufficient number of users of an API,
it does not matter what you promise in the contract:
all observable behaviors of your system
will be depended on by somebody.

By using calver, we as a team are basically acknowledge that we cannot maintain any promise between versions: we could get the same result by using a new major number for every release, but here we are just being very explicit about it.

This is of course very different than saying that we will consciously break compatibility at every commit: we will try to preserve backward compatibility, provide deprecation warnings and migration paths when possible and when it makes sense. Simply, we are not promising anything, which means that if you want to distribute your app, you should just pin the full version of pyscript.

josephrocca · 2022-06-16T08:18:08Z

Happy to keep discussing this if my feedback/thoughts are useful here.

I agree that being able to deploy security fixes to old releases is critical, but as fabio said YYYY.MM.## already addresses this particular issue.

The disadvantage here is that you have to release a fix for every month, versus just for major versions. If you expect to release new breaking changes roughly every month then I agree that this isn't an issue with calver. And if the PyScript contributors try their best to cluster API changes into "distant" releases (as opposed to scattering them whenever, I mean), then that makes calver almost as good as semver in this respect. Semver just tries to make the organisation of breaking changes more explicit.

we could get the same result by using a new major number for every release, but here we are just being very explicit about it.

I don't see why a major version number isn't explicit? It's arguably more explicit to use semver here because that's what the rest of the ecosystem uses - i.e. it's a convention that's very well understood by developers. What does calver add that incrementing the major version doesn't? If the dates are always listed beside package versions in Github releases and package manager listings, then what is the key advantage of calver that makes it worth breaking the JS ecosystem convention? It's fine to increment the major version with every release if significant changes are being made. But if you're changing some internal implementation details (renaming some internal variables, adding some performance improvements, etc.), then you can make that a minor release, and save up the big changes for major releases to help the ecosystem around your project.

I want to re-emphasise that it's completely fine to bump the major version very often. Bumping the major version involves a judgement call based on the number of users your project has, and the "size" of the change, but I think there are clearly changes which don't require a major version bump, and there are clearly benefits to delimiting and clustering likely-breaking API changes. There is of course a grey area, but we ought not to throw up our hands because we can't get perfection here. It's worth considering trade-offs rather than aiming for "perfection or nothing". If in doubt, the major version can always be bumped.

I think a key question at this point in the discussion is: Does calver have any key benefits to just bumping the major version for every release? Is it useful to have to date in the version given that dates are always listed next to releases? And if there aren't significant benefits but the team doesn't want to make any promises at this stage, why break the convention here versus just bumping the major version with each release? I suspect that the team would find that, in fact, there are some releases where no major version bump is practically needed - e.g. tidying up and refactoring, "well-contained" bug fixes, performance optimisations, etc. but semver seems like a better choice even if that weren't the case given the existing strong conventions in web package management.

antocuni · 2022-06-16T09:50:44Z

Happy to keep discussing this if my feedback/thoughts are useful here.

Personally I think they are useful and it's always good to hear different opinion. But at the same time I think this is getting more and more a "philosophical" debate and as such it is less likely to have an impact on the actual decision.

But if you're changing some internal implementation details (renaming some internal variables, adding some performance improvements, etc.), then you can make that a minor release,

that's the main point of disagreement. I (we) think that even changes which look innocent might be backwards incompatible. So we declare beforehand that all versions are potentially incompatible.

Does calver have any key benefits to just bumping the major version for every release?

yes, it removes the burden to think about version numbers.

josephrocca · 2022-06-16T10:39:22Z

it removes the burden to think about version numbers

Is this the only benefit of calver? If so, why not just auto-bump the major version on every release (or use 0.X.X as mentioned previously)? What extra burden does that impose versus calver? Package ecosystem compatibility is valuable, and this seems like a practical/non-philosophical issue.

antocuni · 2022-06-16T11:17:55Z

Package ecosystem compatibility is valuable, and this seems like a practical/non-philosophical issue.

can you elaborate on that? What kind of incompatibilities calver would cause?
(Genuine question here, because in the python ecosystem some projects are using calver without any sort of problem, AFAIK)

josephrocca · 2022-06-16T11:35:34Z

Sure! Basically all packages in the JS ecosystem use semver, and a lot of the tooling in the ecosystem has come to be built upon semver, including all the most popular tools - e.g. npm: https://docs.npmjs.com/about-semantic-versioning I don't think I've ever seen calver or any other versioning system used in JS/web projects - semver has become a very strong convention. As a concrete example example the npm audit tool will provide warnings and potential upgrade pathways to help fix security bugs based on semver: https://docs.npmjs.com/auditing-package-dependencies-for-security-vulnerabilities#security-vulnerabilities-found-with-suggested-updates

antocuni · 2022-06-16T12:06:37Z

So if I understand correctly, the problem is that e.g. npm audit might suggest to update from e.g pyscript 22.6 to pyscript 22.7 because from its point of view it should be a non-breaking change?
Does it only suggest to do it, or there is an actual risk that it actually does it automatically?

josephrocca · 2022-06-16T16:53:55Z

In the particular case of npm au 8000 dit it lists viable fix pathways, and can install the suggestions for you if you add --fix (npm suggests this when a security problem is detected). Of course, it never does anything without informing you what is going to be done.

But note that this is not an npm-specific thing - rather, it's a web ecosystem thing. For example, IDEs, including newfangled and beginner-friendly web-based ones like Glitch have inbuilt tools which lean on semver package versioning.

pww217 · 2022-06-21T14:12:07Z

Framework for release automation in #521

fpliger · 2022-06-21T16:45:47Z

thanks @pww217 !!

Before closing the loop on this one, I want to make sure we covered one thing.

@josephrocca you mentioned that adding a major digit in front of calver would possibly "fix" the issue with the tooling in the JS world... but I'm not quite sure (and may be missing something). Let's say we do that and add a 0 in front for now, so, 0.YYYY.MM.counter... if we keep leaving 0 fixed and keep bumping the rest, how does it help? Any fix recommendation would have the same semantic value in both cases...

josephrocca · 2022-06-21T17:52:30Z

@fpliger in semver, starting the version with 0. is just a way to say (to devs and packaging tools) "the public API may change at any time - no promises":

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

https://semver.org/#spec-item-4

Any fix recommendation would have the same semantic value in both cases...

As an example, if the npm version of the package is 2022.6.1, then npm audit (and perhaps a subset of devs) would assume that 2022.06.2 isn't a breaking change, when it in fact could be. If the version starts with 0., then the packaging tools will always assume that newer versions are breaking.

I've just looked into how people fit calver into semver for npm/packaging compatibility, and it looks like the one approach is to use "prerelease" tag (basically a string/tag after a hyphen at the end of the semver number) to house the calver:

0.0.1-YYYY.M.counter
0.0.YYYY-M.counter
0.YYYY.M-counter

SemVer doesn't allow leading zeros in any of the 3 version numbers, so I think the leading leading zero of single-digit months would need to be dropped.

I think another possibility (that avoids use of prerelease tag and keeps leading zero on month) is just:

0.YYYYMM.counter

jezdez · 2022-06-21T17:58:39Z

Just leaving this here since I've been burned by software in production that had leading zeros: https://0ver.org

josephrocca · 2022-06-21T18:46:02Z

@jezdez Can you share how you were burned, and what might have prevented the problem in your case?

Potentially worth emphasising that the leading zero 'means something' (i.e. no promises made RE public API yet) in the JS ecosystem to the devs and all the popular tooling, so if the burn had to do with confusion around the implication of the leading zero (in a non-JS ecosystem) then it might not be as relevant in this case due to the strong conventions.

fpliger · 2022-06-21T19:45:39Z

I still don't see any benefit from adding a 0. Just trying to fit CalVer into SemVer for the sake of it. The choice of CalVer is explicit exactly because SemVer is not good and relies on promises it can't guarantee.

My question is more specific/explicit: Is there any benefit from the tooling point of view? Because from the semantic point of view, adding a 0 just makes CalVer worse.

In term of tooling. npm CalVer users can still pin versions and use carets ^ and ~ to define version ranges.
“^2022.6.1” would mean they’d get the latest 2022 version.
“~2022.6.1" would mean they’d get the latest 2022.6 version.

Updates will mean different things than SemVer( so with CalVer we’d provide users the ability to easily update per month, automatically track the work over the year, or if explicitly specified update to the new year’s release) but it's intentional. If you are installing PyScript with npm you should pin versions.

josephrocca · 2022-06-21T22:16:25Z

My question is more specific/explicit: Is there any benefit from the tooling point of view?

There must be a misunderstanding here because I thought I answered that specific question here:

As an example, if the npm version of the package is 2022.6.1, then npm audit (and perhaps a subset of devs) would assume that 2022.06.2 isn't a breaking change, when it in fact could be. If the version starts with 0., then the packaging tools will always assume that newer versions are breaking.

npm audit will (incorrectly) not display a warning when suggesting an upgrade: https://docs.npmjs.com/auditing-package-dependencies-for-security-vulnerabilities#semver-warnings In your case if you always want upgrades to display a warning, you should start with a zero, or bump the major version on each release. Starting with a zero seems to make more sense in your case, at least for now.

Because from the semantic point of view, adding a 0 just makes CalVer worse.

From a semantic point of view, within the web ecosystem, adding the leading zero is probably better because the established semantics across the web landscape are such that the leading zero implies exactly what you're trying to imply in this specific case: No promises RE API stability.

If you are installing PyScript with npm you should pin versions.

Agree 100% - and after thinking about this a bit (and after reading this): Since npm install adds a caret to the start of the version string (like ^0.0.1 - which allows patch and minor updates) rather than exact pinning, it might make the most sense to use one of these formats when publishing to npm:

0.0.YYYYMM##
0.YYYYMM##.0

That would ensure that when people install your package, it is exactly pinned by default.

NPM is the defacto package manager for the web (analogous to PyPi), and publishing there will automatically publish your package to several global highly-trusted and robust CDNs like jsdelivr, unpkg, etc. - so it definitely makes sense to publish your package to NPM. And since NPM requires semver, it makes sense to be compliant with semver "rules" when publishing. So you could use calver on Github and for internal tracking, but then publish the NPM version in a specific format (like above) that doesn't "break" normal NPM functionality.

There are some popular JS projects that do this sort of thing - e.g. three.js uses a single number for their version (just increment every release), but they publish to NPM as 0.X.0 (where X is that single number) so it's compatible with all the tooling and is clear to devs that each version should be considered breaking.

pww217 · 2022-06-22T17:33:35Z

Wrapping this up here #539

Assuming it tests through alright, we'll be set for the time being.

fpliger · 2022-06-22T19:24:54Z

Thanks @pww217

@josephrocca I want to wrap this up in a good way since I really appreciate your thoughtful comments on all of that. I've just checked with the core team/maintainers again to make sure if they wanted to change anything given all the feedback. The tldr is that not much has changed or has been added to the discussion in a way that changes the reasons of why choosing CalVer, so the preferences remained as they were. As you mentioned, NPM is the defacto package manager for the web but it doesn't really "require" SemVer. In some sense, some of it's tooling expects projects to adopt SemVer but doesn't really require it (at least to the extent of our knowledge). Some updating strategies will be different for PyScript (based on year, minor, etc... instead of major). It's enough for the team to give it a try. We think this choice is right for the project and its users. If time proves us wrong, we'll always have the door open to change it (to SemVer or another option).

Thanks again for the discussion!

josephrocca · 2022-06-22T21:18:49Z

we'll always have the door open to change it

True! Will be weird to start incrementing from 2022/2023 upwards and away from the actual current year, but not really a big deal.

NPM is the defacto package manager for the web but it doesn't really "require" SemVer.

Yep, it's not "required" in the sense of impossibility, but rather in the sense that it breaks default behavior of npm install, npm audit and the like (and of course same for other popular tools like yarn).

I can't say I really understand why, if you are using any particular package manager, you wouldn't just publish in a format that that package manager understands, since it doesn't affect the actual versioning that you use internally, but your team seems dead set on this and I've done the best I can to communicate the damage it's likely to cause here regarding the default caret with npm install, the fix recommendations/warnings of npm audit, and general (benefit-free, given internal use of CalVer) ecosystem convention-breaking effects.

All I can say now is: Thanks for your patient discussion, and I'm really rooting for you and your project! I'm excited about what you, the Pyodide team, the JupyterLite team, and others working in the "Python x Web" space are doing. So many thousands of person-years have gone into the Python ecosystem, and suddenly unlocking a barrier between it and the web is going to be super valuable to both the web and to Python ecosystems. I can't speak from the Python side of things, but I don't think many people on the web side of things understand just how significant this "unlock" is going to be. Deeply thankful for your work on this - exciting times ahead! 🚀

fpliger · 2022-06-22T21:30:30Z

Yep, it's not "required" in the sense of impossibility, but rather in the sense that it breaks default behavior of npm install

I'm afraid I don't understand this point, so I'll as you to be patient here. The caret (aka hat) symbol, ^ , is used by default when you npm install --save a package. So, if you npm install pyscript it'll save, let's say "^2022.06.01". “^2022.6.1” would mean they’d get the latest 2022 version and after that, they'd need to manually bump the year version. It's a semantic change, not really break to the only "default behaviour". Right?

All I can say now is: Thanks for your patient discussion, and I'm really rooting for you and your project! I'm excited about what you, the Pyodide team, the JupyterLite team, and others working in the "Python x Web" space are doing. So many thousands of person-years have gone into the Python ecosystem, and suddenly unlocking a barrier between it and the web is going to be super valuable to both the web and to Python ecosystems. I can't speak from the Python side of things, but I don't think many people on the web side of things understand just how significant this "unlock" is going to be. Deeply thankful for your work on this - exciting times ahead! 🚀

Thank you for the kind words. I share the excitement for the times ahead and hope we and other communities can indeed improve the "Python for the Web" ecosystem :)

josephrocca · 2022-06-22T22:08:45Z

So, if you npm install pyscript it'll save, let's say ^2022.06.01. ^2022.06.01 would mean they’d get the latest 2022 version and after that, they'd need to manually bump the year version.

Yep, that's correct. The problem here is that if, let's say, the dev publishes their code to Github, and another dev (or the same dev in the future) git clones it and executes npm install to install all the packages, they would actually be installing version 2022.11.09 (the latest 2022 version at the time) which could mean that the code which worked before, no longer works due to breaking changes in PyScript between those two versions.

It's possible to avoid this and get desired "exact-pin" default behavior by publishing to npm as 0.X.0 or 0.0.X where X contains the non-SemVer version (with SemVer-invalid characters removed). So, for example, three.js's current "internal" version string is r141, but they publish to npm as 0.141.0. In your case it'd be something like 0.0.YYYYMM## or 0.YYYYMM##.0. This format indicates to tools (and devs) that all changes are potentially breaking, and so it would also prevent misleading suggestions from tools like npm fix and related tools.

I'm afraid I don't understand this point, so I'll ask you to be patient here.

Of course, happy to help!

fpliger · 2022-06-22T22:28:04Z

Ok. That's exactly what I thought. Just to say it explicitly, by choosing CalVer we are not planning on breaking code/version on every release. :)

Thank you again!

josephrocca · 2022-06-22T23:02:48Z

Ah gotcha, yep if you're only introducing breaking changes on yearly (i.e. "major") releases then the example I gave is not relevant at all - npm install/npm fix/etc. behavior will be correct 👍 Something like 0 9477 .YYYYMM##.0 is just if you think devs should exactly-pin PyScript by default.

fpliger · 2022-06-23T16:40:06Z

closed by #539 🚀 🎉 🎉 🎉

pww217 added the tag: tooling Related to the configuration of infrastructure and tooling label May 26, 2022

fpliger mentioned this issue May 27, 2022

Versioning proposal for PyScript #337

Closed

fpliger assigned pww217 Jun 23, 2022

fpliger closed this as completed Jun 23, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[FEATURE] Versioning and automating versioning #468

[FEATURE] Versioning and automating versioning #468

[FEATURE] Versioning and automating versioning #468

[FEATURE] Versioning and automating versioning #468

Comments