From b9fb3bfd37e41581407172ff82446f793723333e Mon Sep 17 00:00:00 2001 From: jorenbroekema Date: Tue, 22 Feb 2022 14:30:18 +0100 Subject: [PATCH] chore: add documentation about lion versioning --- .changeset/little-owls-perform.md | 6 ++++- docs/docs/rationales/versioning.md | 35 ++++++++++++++++++++++++++++++ 2 files changed, 40 insertions(+), 1 deletion(-) create mode 100644 docs/docs/rationales/versioning.md diff --git a/.changeset/little-owls-perform.md b/.changeset/little-owls-perform.md index 7396d3296..324a8971a 100644 --- a/.changeset/little-owls-perform.md +++ b/.changeset/little-owls-perform.md @@ -39,4 +39,8 @@ 'providence-analytics': patch --- -Upgrade to latest Typescript. Keep in mind, some @ts-ignores were necessary, also per TS maintainer's advice. Use skipLibCheck in your TSConfig to ignore issues coming from Lion, the types are valid. We also unfixed lion's dependencies (now using caret ^) on its own packages, because it caused a lot of problems with duplicate installations for end users as well as subclassers and its end users. Both of these changes may affect subclassers in a breaking manner, hence the minor bump. +Upgrade to latest Typescript. Keep in mind, some @ts-ignores were necessary, also per TS maintainer's advice. Use skipLibCheck in your TSConfig to ignore issues coming from Lion, the types are valid. + +**We also unfixed lion's dependencies (now using caret ^) on its own packages**, because it caused a lot of problems with duplicate installations for end users as well as subclassers and its end users. Both of these changes may affect subclassers in a breaking manner, hence the minor bump. + +Be sure to [read our Rationale on this change](https://lion-web.netlify.app/docs/rationales/versioning/) and what this means for you as a user. diff --git a/docs/docs/rationales/versioning.md b/docs/docs/rationales/versioning.md new file mode 100644 index 000000000..7128444e0 --- /dev/null +++ b/docs/docs/rationales/versioning.md @@ -0,0 +1,35 @@ +# Rationales >> Versioning Lion ||20 + +Since Lion is a monorepository where each package is published separately under the `@lion` scope, we have packages that depend on other packages. + +For example, `@lion/dialog` has a dependency on `@lion/overlays`. + +The way we now version those is with `^` carets, for example: + +```json +{ + "dependencies": { + "@lion/overlays": "^0.30.0" + } +} +``` + +This means: + +- For versions >= 1.0.0, get the latest minor of a certain major, major upgrades may contain breaking changes +- For versions < 1.0.0, get the latest patch of a certain minor, minor upgrades may contain breaking changes + +See also, [Semantic Versioning](https://semver.org/). + +In the past, we used to have fixed versioning, our rationale was as follows: + +> Given there is a subclasser that consumes lion and publishes their own component set, each installation of a certain version of that component set must have the exact same versions of lion installed, so that the experience of the end user is consistent. + +**However**, if semver is followed properly, users should never get the situation where they get diverging experiences, because that would only happen in a breaking change. +Additionally, fixing the versions led to other problems: + +- Undedupable installations of the same package. If there are two installations of `@lion/button` and one is installed as a dependency of another lion package, this installation will never be able to be deduped to another version, even if they're on the same minor. This is because the dependency is set to a fixed version, so NPM will see the two installations as incompatible and not dedupe them. For Lion, this can definitely lead to problems, especially with packages like `@lion/form-core`, `@lion/localize`, `@lion/overlays`, due to the singleton nature of some of the parts in those packages. +- Importing directly from lion as an end user when consuming a subclasser package that uses lion under the hood is dangerous. This is because you will need to always match, **exactly**, the version that is installed by the subclasser package. This means syncing your lion version with the subclasser's installed lion version every time you upgrade. +- Changesets will see (correctly) every bump in a `@lion` dependency as a semver-incompatible change for its `@lion` dependents and bump them as a result. This means a change to `@lion/core`, no matter how tiny, will bump almost every other `@lion` package "unnecessarily". This results in large changelogs that are mostly meaningless noise, hardly "human readable" which is the goal of changesets when used correctly. + +Given all this, we changed our approach to versioning and went back to using `^` carets in our versions and **our new recommendation is to depend on `@lion` with `^` carets**. This should prevent majority of undedupable installation problems our users were having, allow importing from `@lion` directly, more safely, make our changelogs cleaner and reduce our publishing bloat.