docs: Add Frontend Dependency Freeze ADR #753

arbrandes · 2025-11-20T14:20:42Z

Do it under OEP-0010, since it is mostly about releases and release schedules.

oeps/processes/oep-0010/decisions/0001-frontend-dependencies.rst

bradenmacdonald · 2025-11-20T19:09:52Z

Could we do this in a simpler way, by saying that the versions of these major dependencies should be specified by frontend-base [only], not individual MFEs, and then that all MFEs need to use the same version of frontend-base for each release?

arbrandes · 2025-11-21T17:50:30Z

@bradenmacdonald, somewhat surprisingly, in the beginning of the development of frontend-base we ran into problems tyring to do just that. I forget what the hitch was (it could have been due to module federation, or maybe just Typescript not working properly after a local npm ci... or something else; probably good to try it again) , but the result was that we ended up having to put the full peerDeps in all repos.

That said, this ADR is more about the communication and less about the mechanics. Sure, we can try to code the consequences as simply as we can (including what you suggested), but we still need to decide - as early as we can - what version of React we're going to use for Verawood, Wyllow, and so on, and then to communicate that out to maintainers/developers.

sarina · 2025-12-08T13:45:34Z

@arbrandes how can we get this merged?

arbrandes · 2025-12-08T20:14:33Z

I haven't seen any more objections, so I guess we're good to change it to Accepted and then to merge it!

And do it under OEP-0010, since it is mostly about releases and release schedules.

arbrandes · 2025-12-08T20:22:20Z

@sarina, mind giving it a thumbs up?

sarina · 2025-12-08T22:53:15Z

I think I'd prefer for someone on the FWG to give final approval :)

sarina · 2026-01-05T16:06:03Z

@feanil this was discussed in the last maintenance WG, we'd appreciate if you could take a look!

brian-smith-tcril

Overall this looks great! I left a few comments with thoughts/questions. Looking forward to hearing back!

oeps/processes/oep-0010/decisions/0001-frontend-dependency-freeze.rst

brian-smith-tcril · 2026-01-06T17:17:53Z

oeps/processes/oep-0010/decisions/0001-frontend-dependency-freeze.rst

+
+Once the Dependency Freeze is announced, frontend maintainers must abide by it for the duration of a given release cycle.  Speficically, this means that on all main branches, corresponding dependencies should not be bumped beyond the defined versions from the moment of the announcement until immediately after the cutoff.  And on release branches, the same applies for the life of the branch.  This constraint will not only give developers, testers, and ultimately, users, a firmer base to work off from, but also a more consistent one both visually and under the hood.
+
+Patch version updates are not foreseen to be problematic, as in a frontend-base paradigm the dependency versions this ADR concerns itself with will be configured with a ``^`` (caret) prefix as ``peerDependencies`` in all relevant ``package.json`` files. In practice, this means that whenever a new non-major (i.e., non-breaking) version of a library is published, it ends up being used automatically by all apps at build time as a result of NPM's deduplication algorithm. In other words, there's no need to issue a PR to every single ``package.json`` just because a bug was fixed in Paragon.


Patch version updates

configured with a ^ (caret) prefix

^ allows for greater minor/feature versions as well.

I think a bit of clarity around how the freeze works would be helpful.

MFE apps:

Use "compatible" (^) in peerDependencies in package.json, this enforces

Maximum AND minimum major/breaking version (these are the same number) (^6 or just 6 are valid and equivalent in package.json)

(Optionally) minimum minor/feature version (^6.3 is valid in package.json)

(Optionally) minimum patch/fix version (^6.3.1 is valid in package.json)

frontend-base itself (I'm not sure here), are we:

Using explicit (6.3.1) versions? Are we manually bumping patch versions for frontend-base itself?

Using "approximate" (~6.3.1) versions?

Yea, I agree here, more documentation on what exactly you want folks to pin to with an example would be helpful for connecting the abstract goal to concrete actions.

Agreed. I added explicit instructions to the Decision section.

As for major vs minor vs patch in peerDeps, I think we should stick to ^<major>. It's both expressive and simple. And, of course, it does what we need it to do.

Regarding frontend-base, I see no reason not to do the same thing in its package.json, at least as far as this ADR is concerned. Sure, there will situations where we want to be more specific (buggy patch versions come to mind), but as long as we don't explicitly forbid being more specific here, I think in the ADR it should be lumped in with everything else.

(If we ever want a more nuanced version control strategy, it probably deserves its own ADR in frontend-base itself. This one's more about release coordination around major versions.)

The new wording in 6da649e is very clear! LGTM!

brian-smith-tcril · 2026-01-06T17:23:51Z

oeps/processes/oep-0010/decisions/0001-frontend-dependency-freeze.rst

+
+Otherwise, we reject a smaller set of frozen dependencies.  The proposed list is considered to be the smallest one that still achieves the goals of consistency, maintainability, UX, and DX.  Notably, not freezing Paragon can lead to significant UX consistency issues, and the freezing of Frontend Base is a fundamental technical requirement for all apps built on it - not to mention the benefits we get from de-duplication.  The latter, in turn, necessitates the freezing of the other dependencies such as React itself, which doesn't support having multiple versions running on the same web page.
+
+We also reject a larger, more prescriptive set of dependencies.  While more may eventually be added to the list, developers are, in principle, free to add other requirements to individual package.json files, even if different apps end up using different versions of the same dependency.


Probably out of scope for this ADR, but we should probably start thinking about a process for "auditing" MFE app dependencies to see if we should move them up frontend-base/to peer in the apps.

I assume for the first few releases it'll be a non-issue as ^ versioning of the same dependencies used in multiple MFE apps will "just work" to dedupe, but as time goes on and some MFE apps are more actively maintained than others that could change.

Agreed: both that it's out of scope here, and that we should start thinking about it. :)

I imagine the first time this comes up organically it'll be when some older app uses, say (since it actually happened recently) react-query v4, while another users react-query v5, and something breaks when they're built together via frontend-base, before this ADR added react-query to the list.

I feel like we can just cross that bridge when we get there. In all likelihood, somebody will report a bug, and to fix it we'll just add the dep to the list. 🤷🏼‍♂️

sarina · 2026-01-14T14:03:40Z

@arbrandes ping - could you please reply to review comments?

@feanil ping - could you take a review pass?

feanil

A couple of comments but the overall approach makes sense to me. I want to push us to make tickets where possible for this and also agree with @brian-smith-tcril that tooling to detect repos that are out of compliance will be important. The repo-health-checks tooling might be useful here and worth looking into as follow-up work.

oeps/processes/oep-0010/decisions/0001-frontend-dependency-freeze.rst

feanil · 2026-01-14T15:32:12Z

oeps/processes/oep-0010/decisions/0001-frontend-dependency-freeze.rst

+
+(This list may be modified in the future to reflect changes in the technology stack, such as those stemming from changes to :ref:`OEP-67 <OEP-67 Standard Tools and Technologies>` or the introduction or removal of an Open edX library.)
+
+The decision will be posted in the appropriate public channels, so that by the time of the cutoff, all aforementioned repositories' main branches must be using the corresponding versions.


What about creating tickets on all repos that need to be in sync, then maintainers just need to track issues on their repo which is something we want them to be doing anyway. It also gives us good visibility into completion status with a parent ticket.

Agreed. Added as a specific type of public channel.

feanil · 2026-01-14T15:34:34Z

oeps/processes/oep-0010/decisions/0001-frontend-dependency-freeze.rst

+
+Once the Dependency Freeze is announced, frontend maintainers must abide by it for the duration of a given release cycle.  Speficically, this means that on all main branches, corresponding dependencies should not be bumped beyond the defined versions from the moment of the announcement until immediately after the cutoff.  And on release branches, the same applies for the life of the branch.  This constraint will not only give developers, testers, and ultimately, users, a firmer base to work off from, but also a more consistent one both visually and under the hood.
+
+Patch version updates are not foreseen to be problematic, as in a frontend-base paradigm the dependency versions this ADR concerns itself with will be configured with a ``^`` (caret) prefix as ``peerDependencies`` in all relevant ``package.json`` files. In practice, this means that whenever a new non-major (i.e., non-breaking) version of a library is published, it ends up being used automatically by all apps at build time as a result of NPM's deduplication algorithm. In other words, there's no need to issue a PR to every single ``package.json`` just because a bug was fixed in Paragon.


Yea, I agree here, more documentation on what exactly you want folks to pin to with an example would be helpful for connecting the abstract goal to concrete actions.

arbrandes · 2026-01-21T15:15:18Z

I've addressed the latest comments.

brian-smith-tcril

arbrandes · 2026-01-28T10:58:09Z

@feanil, want to give it a last browse? Can we merge it?

arbrandes force-pushed the frontend-dependencies-adr branch from 2cafddf to 4f75dd1 Compare November 20, 2025 14:26

sarina reviewed Nov 20, 2025

View reviewed changes

arbrandes commented Nov 20, 2025

View reviewed changes

oeps/processes/oep-0010/decisions/0001-frontend-dependencies.rst Outdated Show resolved Hide resolved

arbrandes commented Nov 20, 2025

View reviewed changes

oeps/processes/oep-0010/decisions/0001-frontend-dependencies.rst Outdated Show resolved Hide resolved

arbrandes commented Nov 20, 2025

View reviewed changes

oeps/processes/oep-0010/decisions/0001-frontend-dependencies.rst Outdated Show resolved Hide resolved

arbrandes force-pushed the frontend-dependencies-adr branch from 4f75dd1 to 6803bc4 Compare November 21, 2025 17:56

arbrandes changed the title ~~docs: Add Frontend Dependencies ADR~~ docs: Add Frontend Dependency Freeze ADR Nov 21, 2025

docs: Add Frontend Dependency Freeze ADR

5aae89c

And do it under OEP-0010, since it is mostly about releases and release schedules.

arbrandes force-pushed the frontend-dependencies-adr branch from 4e749a0 to 5aae89c Compare December 8, 2025 20:20

sarina requested a review from feanil January 5, 2026 16:05

brian-smith-tcril self-requested a review January 5, 2026 16:05

brian-smith-tcril reviewed Jan 6, 2026

View reviewed changes

feanil reviewed Jan 14, 2026

View reviewed changes

fixup! docs: Add Frontend Dependency Freeze ADR

6da649e

brian-smith-tcril approved these changes Jan 21, 2026

View reviewed changes

feanil approved these changes Jan 28, 2026

View reviewed changes


		Once the Dependency Freeze is announced, frontend maintainers must abide by it for the duration of a given release cycle. Speficically, this means that on all main branches, corresponding dependencies should not be bumped beyond the defined versions from the moment of the announcement until immediately after the cutoff. And on release branches, the same applies for the life of the branch. This constraint will not only give developers, testers, and ultimately, users, a firmer base to work off from, but also a more consistent one both visually and under the hood.

		Patch version updates are not foreseen to be problematic, as in a frontend-base paradigm the dependency versions this ADR concerns itself with will be configured with a ``^`` (caret) prefix as ``peerDependencies`` in all relevant ``package.json`` files. In practice, this means that whenever a new non-major (i.e., non-breaking) version of a library is published, it ends up being used automatically by all apps at build time as a result of NPM's deduplication algorithm. In other words, there's no need to issue a PR to every single ``package.json`` just because a bug was fixed in Paragon.


		Otherwise, we reject a smaller set of frozen dependencies. The proposed list is considered to be the smallest one that still achieves the goals of consistency, maintainability, UX, and DX. Notably, not freezing Paragon can lead to significant UX consistency issues, and the freezing of Frontend Base is a fundamental technical requirement for all apps built on it - not to mention the benefits we get from de-duplication. The latter, in turn, necessitates the freezing of the other dependencies such as React itself, which doesn't support having multiple versions running on the same web page.

		We also reject a larger, more prescriptive set of dependencies. While more may eventually be added to the list, developers are, in principle, free to add other requirements to individual package.json files, even if different apps end up using different versions of the same dependency.


		(This list may be modified in the future to reflect changes in the technology stack, such as those stemming from changes to :ref:`OEP-67 <OEP-67 Standard Tools and Technologies>` or the introduction or removal of an Open edX library.)

		The decision will be posted in the appropriate public channels, so that by the time of the cutoff, all aforementioned repositories' main branches must be using the corresponding versions.

docs: Add Frontend Dependency Freeze ADR #753

Are you sure you want to change the base?

docs: Add Frontend Dependency Freeze ADR #753

Conversation

arbrandes commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bradenmacdonald commented Nov 20, 2025

Uh oh!

arbrandes commented Nov 21, 2025

Uh oh!

sarina commented Dec 8, 2025

Uh oh!

arbrandes commented Dec 8, 2025

Uh oh!

arbrandes commented Dec 8, 2025

Uh oh!

sarina commented Dec 8, 2025

Uh oh!

sarina commented Jan 5, 2026

Uh oh!

brian-smith-tcril left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sarina commented Jan 14, 2026

Uh oh!

feanil left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arbrandes commented Jan 21, 2026

Uh oh!

brian-smith-tcril left a comment

Choose a reason for hiding this comment

Uh oh!

arbrandes commented Jan 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

arbrandes commented Nov 20, 2025 •

edited

Loading