8000 Versioning proposal for PyScript · Issue #337 · pyscript/pyscript · GitHub
[go: up one dir, main page]
Skip to content

Versioning proposal for PyScript #337

New issue

Have a question abou 8000 t this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
fpliger opened this issue May 11, 2022 · 14 comments
Closed

Versioning proposal for PyScript #337

fpliger opened this issue May 11, 2022 · 14 comments
Labels
ideas Ideas worth exploring status: accepted PR that has been reviewed and accepted tag: docs Related to the documentation type: feature New feature or request

Comments

@fpliger
Copy link
Contributor
fpliger commented May 11, 2022 •
edited by jezdez
Loading

Skipping versioning the project was an intentional choice that allowed us to focus on the minimal usable version very fast. Now that we have users starting to try PyScript and engage with the project, it's basically an urgent need for us to choose a versioning system for PyScript so that we can better speak in terms of planning & roadmap, support and feedback (users can refer to specific version when bug reporting), and discussions.

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 these reasons, I'd like to propose that we adopt Calver as a versioning convention. It seems to be a good fit in terms of capturing the progression/maturity of versions in time and allows us to not overpromise on stability as we roll out new versions (especially important for where PyScript is today vs the interest shown by the community). It also makes it easier in terms of not having to overthink version numbers when we are introducing new features vs. feature changes vs bugfixes, etc..

Semver is the other obvious option to take into consideration since it's pretty much the standard for a lot of projects but, for the reasons described above, I'd put my vote on Calver.
@fpliger fpliger added type: feature New feature or request tag: docs Related to the documentation labels May 11, 2022
@pnhearer
Copy link

Semver

@animesh-workplace
Copy link

calver

@ryansobol
Copy link

As you said, either versioning schemes will meet the stated requirements. If you're looking for more constructive feedback, it may be helpful to include some examples with the proposal.

As a singular piece of anecdotal data, if my team were to consider adopting PyScript to build a multi-year Python curriculum for K-12 students, which would include thousands of apps pinned to exact versions, we would need clear, transparent, and detailed communication on what breaking changes, if any, are included in each released version.

@sugatoray
Copy link
Contributor
sugatoray commented May 12, 2022 •
edited
Loading

✅ Voting for Calver: YYYY.0M.0D (example: 2022.07.04)

@philippjfr
Copy link
Contributor

My vote is also for CalVer.

@antocuni
Copy link
Contributor

While we are adding versioning, we should also add/considering SRI, as suggested by #326

@ryansobol
Copy link

Voting for Calver: YYYY.0M.0D (example: 2022.07.04)

If standard CalVer is used, how would breaking changes be captured in the versioning scheme?

@sugatoray
Copy link
Contributor
sugatoray commented May 13, 2022 •
edited
Loading

Voting for Calver: YYYY.0M.0D (example: 2022.07.04)

If standard CalVer is used, how would breaking changes be captured in the versioning scheme?

@ryansobol It's a good question. Let's see what others have to say on this. Also, please share your thoughts on my proposal below.

A. Here are my initial thoughts:

  1. Is maintaining a semver-like convention for identifying breaking changes absolutely necessary?

  2. Calver docs show that some of the libraries that use it, have often chosen a hybrid approach to fusing Calver + Semver.

  3. If Major.Minor.Micro (X.Y.Z) convention is used with the underlying assumption that whenever Major version number changes, it signals a breaking change, perhaps something like the following hybrid versioning could allow the benefit of both Semver and Calver.

  • Structure of X.Y.Z : <Major>.YYYY0M.0D<Micro> or shorter <Major>.YY0M.0D<Micro>.

    For example (hypothetically), if while releasing major version 1, on 02-Jan-2023, say the first micro version 0, some important changes were necessary to be released as a second micro version (1), then the two versions could be written as:

    • Micro version 0: 1.202301.020 (shorter: 1.2301.020)
    • Micro version 1: 1.202301.021 (shorter: 1.2301.021)

    🎁 Benefits:

    • Follows Semver like structure (so breaking changes can be communicated with generally known concepts of Semver).
    • The Minor branch contains the year and month information from Calver and so it clearly tracks the time when this was released.
    • The X.Y.Z structure has a Z part composed of hybrid 0D<Micro>. This still confirms to Semver structure (but always will have 3 digits in the place of Z in X.Y.Z and the lowest value possible will be 010)
    • The hybrid X.Y.Z could still be probed with python packages for major, minor and micro versions and compared, as it is all numeric and it only keeps increasing with time.
    • The lowest possible value of any released version will be (for example, if released on 13-May-2022):
      • Long form: 0.202205.130
      • Short form: 0.2205.130

B. Other thoughts:

  1. Making GitHub releases first, followed by pushing to AWS will be helpful.

  2. AWS storage should have paths with endpoints to specific released versions (if that's not setup already).

    • Example: aws/path/to/pyscript/v<VERSION>/file.ext.
    • This will help in identifying which specific version of PyScript was used in any html file.

  3. Also, for the sake of convenience, another endpoint without any specific version (if available) will be helpful, and this should always point to the latest released (stable) version.

    • Example: aws/path/to/pyscript/vstable/file.ext.
    • Keeping the vstable keyword will be self-identifying it as the latest stable version.
    • If additionally, the html file is version tracked with git, a git-blame of the file will be enough to reveal the date when some update was made to the file (if numeric version is not used in the remote-css or remote-js links). And the date, in turn, will be sufficient to determine which was the latest released stable version in use at that time.

cc: @philippjfr @fpliger @antocuni

@ryansobol
Copy link
ryansobol commented May 18, 2022 •
edited
Loading
  1. Is maintaining a semver-like convention for identifying breaking changes absolutely necessary?

After much deliberation, my team came to the conclusion that, yeah, it would be necessary if we were to adopt PyScript for our use cases.

  1. If Major.Minor.Micro (X.Y.Z) convention is used with the underlying assumption that whenever Major version number changes, it signals a breaking change, perhaps something like the following hybrid versioning could allow the benefit of both Semver and Calver.

If the team is dead-set on CalVer, and is considering a hybrid versioning scheme, is there any reason why it must be composed of exactly three version components?

Structure of X.Y.Z : <Major>.YYYY0M.0D<Micro> or shorter <Major>.YY0M.0D<Micro>.

Why not just Major.Year.Month.Day? For example, 1.2023.01.02? The parsing algorithm for both humans and machines would be much simpler.

I would also like to point out that plain-old SemVer would work for our use cases as end-users.

@fpliger
Copy link
Contributor Author
fpliger commented May 19, 2022

Thanks @ryansobol @sugatoray and everyone for chiming in and expressing your thoughts here.

Here is a great post, that I'd like to share in the discussion, about versioning and how semver is not always the silver bullet for versioning.

Personally, I'm way more experienced with semver than calver, given that it's been the versioning convention for most of the projects I was part of in the past. My experience is that it will not guarantee that things will not break. There's a difference between best intentions, code changes, API changes, etc... Developers spend a great amount of thought to comply with the versioning structure and what's the right next version while, ultimately, user code is really the real test to determine if a version is a breaking version or not. I suggest reading the article above for a better and deeper analysis of the problem...

calver doesn't imply that users should expect every new version to break previous code nor the contrary. It's mainly a measure of evolution in time and "how far am I from the latest version".

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.

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.

In the scenario above, we can use the <py-config> component to actually allow users to specify what API versions they want to use in their app. The [Calver] version of the Framework should pin the default version it supports (so users upgrading can now that it'll break for them) but they can always pin the API version in their config at anytime.

@ryansobol I actually thought about the model your are proposing of Major.Year.Month.Daybut ultimately have been thinking that the proposal above is more solid and flexible.

@fpliger fpliger mentioned this issue May 19, 2022
Closed
@fpliger fpliger added the ideas Ideas worth exploring label May 23, 2022
@fpliger
Copy link
Contributor Author
fpliger commented May 23, 2022

Given the votes and overall 👍 on this (and no objections after the amended proposal) I'd call this decided and we can start implementing it this week.

Thanks, everyone! 🙌

/cc @pww217

@ryansobol
Copy link

Thanks for considering my input, @fpliger! Though I’m not sure I fully understand the example scenario above, I appreciate being heard, and it sounds like both communicating breaking changes via the versioning scheme and anticipating a future with deprecation cycles are still on the table. My team and I eagerly await the implementation details. 😄

@fpliger fpliger added the status: accepted PR that has been reviewed and accepted label May 27, 2022
@fpliger
Copy link
Contributor Author
fpliger commented May 27, 2022

Closing this as accepted now that we also have #468 to follow up on actual work after this decision. Thanks to everyone who participated!! 🎉

@fpliger fpliger closed this as completed May 27, 2022
@josephrocca josephrocca mentioned this issue Jun 12, 2022
Closed
@WebReflection
Copy link
Contributor
WebReflection commented Sep 15, 2023 •
edited
Loading

Not sure if worth re-opening this, but if this was the reason to pick Calver:

It seems to be a good fit in terms of capturing the progression/maturity of versions in time and allows us to not overpromise on stability as we roll out new versions (especially important for where PyScript is today vs the interest shown by the community)

I wonder when we'd like to draw a line and communicate out there that PyScript is now stable.

My experience is that it will not guarantee that things will not break

a major semver change is guaranteed to break (in a way or another), a minor is to bring in new features, a patch is for bugs fixes ... but there's more to it ...

  • a breaking new version of PyScript can't be captured by Calver
  • a new version of PyScript released in the same year previous version exists, also is not captured by Calver
  • a project in the major is considered stable by semver definition of major, a forever breaking versioning feels so odd, projects like Ubuntu (thanks @antocuni) decided to release twice per year, implicitly bumping major each year
  • we're planning to release PyScript "next" and do it monthly ... as the project is a whole rewrite and features will be added at fast pace, it's impossible to understand what Calver means ... as any month update doesn't reflect that
  • if I use sqlite 3.x it doesn't matter if it's from 5 years ago or the latest, I know I am using a rock-solid version of sqlite
  • if I use sqlite 2016 you can feel the goosebumps instead ... as that feels old already, even if maybe that year that was the most stable and widely deployed version ... nobody would guess that from that versioning, they'll just think it's old

I have no other points to add but to me, looking around at the industry we are, everyone, including Python uses semver or something close to it ... browsers, Operating Systems, programming languages (oddly enough ECMAScript is an exception here, but they also don't release monthly, rather 3 features in each year) so if you feel like times are different today, and we'd like to communicate we're out of perpetual experimentation after years of experience with the project, please re-open this and let's publish our first v1.0.0 out of what we believe is the right path and code-base to build on for the near to the next future.

edit

As last stroke to me ... with Calver we can't back-port fixes or changes to a previous release, as these won't make sense once published with a date ... so we are intentionally ditching PyScript "classic" support forever if we release PyScript "next" branch via Calver, as opposite of having a v0 (classic) VS v1 (next) anyone can pin-point to without having ever any confusion.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
ideas Ideas worth exploring status: accepted PR that has been reviewed and accepted tag: docs Related to the documentation type: feature New feature or request
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
8 participants
@ryansobol @WebReflection @antocuni @pnhearer @fpliger @philippjfr @sugatoray @animesh-workplace
0