search

tutors-sdk / tutors

The core Tutors Reader application.
https://tutors.dev
MIT License
107 stars 38 forks source link

Tutors Version Management #702

Open edeleastar opened 5 months ago

edeleastar commented 5 months ago

Introduce & document strategy for managing updates to tutors versions as new releases are deployed. Currently the version number reported in hard coded in a string:

lgriffin commented 1 month ago

Hey @edeleastar I'd have an interest in helping out here. The standard semver approach is what you are looking for here or at least a version you can be inspired by. https://github.com/tutors-sdk/tutors/blob/development/package.json is the authoritative source of the version of the application and there's a mismatch there between the link in the issue, 9.0.0 Vs 10.1.0

Semver is based on X.Y.Z format or Major.Minor.Patch. In short: Major breaks things and requires code changes by your users e.g. a modified API or functionality being removed Minor is where you can add new features safely as they don't need to change anything they built but they can now access new functionality Patch is your typical bug fixes and minor changes that don't change the API contract or expectations, it resolves an issue in the internals of a function. This also applies to things like dependency bumps etc.

My recommendation is to adopt a starting version number, that can be anything you want and it can represent the effort and history. I can write up a small guidance doc on the usage and some of it is behavioral so if you see a PR come in that doesn't include a modification on the package.json you need to get the user to update it. Let me know what you think

edeleastar commented 3 weeks ago

HI @lgriffin

agree with all of the above - we had it for a while but were not at all disciplined about it (by we I mean me).

There is also the issue of versioning the cli - which I have been doing (as npm publish will not let you away with not thinking it through). However, there are subtle dependency issues between the CLI and the Reader, which have yet to find a solid engineering solution.

At the moment, the tutors model is duplicated (I know!) in both cli and reader. This is a fall back after several suboptimal attempts at shared libraries, monorepos and the like. All previous attempts at a shared code base (for command line ts apps and vite driven svelte apps) have had serious flaws.

This is the CLI Learning Object model:

This is the Reader Learning Object Model: