docs: Adding ADRs 0002, 0003 and a glossary to OEP-65 #626

davidjoy · 2024-08-28T20:10:01Z

This PR includes a bunch of stuff:

It adds two new ADRs to OEP-65 about frontend app migrations and frontend projects.
It adds a glossary to OEP-65 in a separate document.
It updates OEP-65 to use that glossary, and freshens up its language based on the terms in the glossary/the ADRs.
It updates ADR 0001 about the unified platform library similarly, noting that https://github.com/openedx/frontend-base is that library.
It adds a short recommendation to OEP-65 around choosing a single, consistent major version for each shared dependency provided by frontend-base for a given Open edX release.

openedx-webhooks · 2024-08-28T20:10:06Z

Thanks for the pull request, @davidjoy!

What's next?

Please work through the following steps to get your changes ready for engineering review:

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
- This process (including the steps you'll need to take) is documented here.
If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

Dependencies

This PR must be merged before / after / at the same time as ...
Blockers

This PR is waiting for OEP-1234 to be accepted.
Timeline information

This PR must be merged by XX date because ...
Partner information

This is for a course on edx.org.
Supporting documentation
Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

🔘 Let us know that your PR is ready for review:

Who will review my changes?

This repository is currently maintained by @sarina. Tag them in a comment and let them know that your changes are ready for review.

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

The size and impact of the changes that it introduces
The need for product review
Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

brian-smith-tcril

This looks great! I left a couple comments to start a couple conversations about how to communicate the changes, but the changes themselves are awesome!

oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst

Also fixing a broken link in oep 65 and the title of ADR 0001, which doesn’t need to say “OEP-65” in it.

Subsequent commits will start using this glossary via :term: roles.

Also linking out to other documents more liberally.

…2 and 3 This also liberally uses the glossary in the ADR.

This commit updates the language of OEP-65 to match its three ADRs, and also makes use of the frontend glossary where possible. Many of the terms used in the glossary don’t actually come up in the OEP.

arbrandes

This is awesome, thank you! I'm on the cusp of approving it, but as per the review comments, I'd like to discuss a couple of the choices first.

arbrandes · 2024-09-24T16:12:55Z

oeps/architectural-decisions/oep-0065-arch-frontend-composability.rst

@@ -245,8 +248,12 @@ Process

 We need to ensure maintainers and developers know what dependency versions to use, and when they need to upgrade to stay consistent. Open edX release documentation should include information on which frontend dependency versions are compatible with the release, likely pinned to a major version (i.e., React 17.x, Paragon 22.x, etc.)

+Further, we recommend that each Open edX release have a single supported major version of all shared dependencies, and that all MFEs be upgraded to it prior to release.


Excellent addition.

arbrandes · 2024-09-24T16:57:41Z

oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst

+* Use the :term:`shell` to provide the header, footer, and runtime initialization code, amongst other things.
+* Organize their code into loosely-coupled top-level components, which are called :term:`application modules <Application Module>`.
+
+As we adopt ``frontend-base``, the libraries it replaces will undergo their own deprecation processes, which will need to coordinate with the migration of micro-frontends included in Open edX releases. After that deprecation, the micro-frontend architecture will cease to be supported.


Suggested change

As we adopt ``frontend-base``, the libraries it replaces will undergo their own deprecation processes, which will need to coordinate with the migration of micro-frontends included in Open edX releases. After that deprecation, the micro-frontend architecture will cease to be supported.

As we adopt ``frontend-base``, the libraries it replaces will undergo their own deprecation processes, which we'll need to coordinate with the migration of micro-frontends included in Open edX releases. After that deprecation, the micro-frontend architecture will cease to be supported.

arbrandes · 2024-09-24T17:01:58Z

oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst

+Decision
+********
+
+Each of our ``frontend-app-*`` repositories will migrate from being an independent "micro-frontend application" to being a library of modules that can be loaded into a common :term:`Shell`, deployed as a :term:`Site`. These are called :term:`application module libraries <Application Module Library>`. We will document the migration process in detail. At a high level, this will involve the following changes.


I think I understand why "Application Module Library" (each former MFE will in theory be able to export multiple modules, making it a library), but I have to ask: would trimming it to "Application Module" also work? It would be easier to remember, pronounce, etc.

Also, if we make the new name too difficult (however accurate), people will just fall back to calling them MFEs. (Which people probably will anyway. 🤷)

I think I'm going to drop the word "Application" from it so that it's just 'module library'. I think we should consider, at some point, whether these repos get renamed to be prefixed with frontend-library- or something; I'm not prepared to bite off a real suggestion there yet. :)

arbrandes · 2024-09-24T17:03:44Z

oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst

+The ``fedx-scripts`` CLI tools from ``frontend-build`` will be replaced with the ``openedx`` CLI tools from ``frontend-base``. We'll discuss some of them in detail here, as they help illustrate what the library will be able to do:
+
+* ``dev`` will start a dev server, loading the repository's application modules into the shell in a site.
+* ``dev:module`` will start a dev server that provides the application modules via module federation.


arbrandes · 2024-09-24T17:05:39Z

oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst

+* ``serve`` will work with ``build`` or ``build:module`` to locally serve the production assets they generated.
+* ``pack`` will work with ``release`` to create a ``.tgz`` file suitable for installing in local git checkouts that depend on the library. (this is a development tool)
+
+The ``dev``, ``dev:module``, ``build``, and ``build:module`` CLI commands will rely on the existence of a :term:`Site Config` file (the replacement for .env/env.config files) which will not be checked into the repository.


Not necessarily a suggestion, but a request for clarification:

Suggested change

The ``dev``, ``dev:module``, ``build``, and ``build:module`` CLI commands will rely on the existence of a :term:`Site Config` file (the replacement for .env/env.config files) which will not be checked into the repository.

The ``dev``, ``dev:module``, ``build``, and ``build:module`` CLI commands will rely on the existence of a :term:`Site Config` file (the replacement for .env/env.config files) which will not be checked into the module repository.

The config file will be checked into a repository (the project's, I suppose), just not the module's... right?

Good clarification, fixing.

arbrandes · 2024-09-24T17:11:28Z

oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst

+
+Our definition of :term:`module` aligns with the `industry standard definition <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules>`_. It is also used in the context of `module federation <https://module-federation.io>`_. It's a self-contained part of the frontend that represents a specific part of the :term:`Site`, and can be loaded in a variety of ways. We have several sub-types of module:
+
+* An *application module* represents a well-bounded sub-area of the Open edX frontend at a particular route path. This might be "courseware", "the login page", or "account settings". There are a number of application modules that are *required* for a functioning Open edX frontend Site.


As per a previous review comment, I feel "application module" can double as the name for the whole thing (sans library at the end).

Maybe another way to think about it is that different modules should live in different repos, lest we fall into the mono-repo issues we've discussed in the past.

We talked about this offline, but for posterity - there are two related rationales for keeping modules (particularly application modules, which are generally pretty big) in the same repository together. These are:

If they share code with other modules in the library. If we split them up and have to create a secondary library to share code between them, we probably haven't made our lives better.

If they're part of the same conceptual 'domain' of the site. This was the original idea behind the MFE boundaries we have today, though we didn't execute it consistently. Some are too big, some are too small. It seems very reasonable to me that the learning-related stuff could be in "frontend-app-learning", and the user account/authentication related stuff would be in something like "frontend-app-user", which doesn't exist.

arbrandes · 2024-09-24T17:12:17Z

oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst

+
+Addressing our *lack* of dependency version consistency is one of the primary drivers of OEP-65.
+
+The shell will support specific versions of shared dependencies (such as React, Paragon, or React Router). All applications loaded into the shell's Site will be expected to use (or at least be compatible) with that version. We intend to create lock-step version consistency of shared dependencies across all applications in the platform. We envision each Open edX release supporting a particular major version of each shared dependency.


arbrandes · 2024-09-24T17:24:57Z

oeps/architectural-decisions/oep-0065/decisions/0003-frontend-projects.rst

+5. The Shell initialization code imports the :term:`Site Config` (i.e., ``site.config.build.tsx``) file from the project.
+6. The :term:`Site Config` file imports any :term:`Application Modules <Application Module>` from libraries it depends on (defined as ``dependencies`` in package.json), along with any other Modules from the ``src`` sub-folder.
+
+Module Projects


While Site Projects are clear to me off the bat, I'm wondering why we also need module projects. I suspect this is a consequence of the different ways modules can be built, but I was under the impression different package.json build targets in the modules themselves would be enough.

I'm putting a clarifying paragraphs about why the two exist at the top of their sections, which hopefully clears it up a bit.

sarina · 2024-10-16T12:52:19Z

@davidjoy @arbrandes -- what's left on this one?

davidjoy · 2024-10-16T13:13:02Z

Just awaiting final review. Didn't want to bug Axim during the on-site week.

sarina · 2024-10-21T13:20:14Z

@arbrandes - any timeline for a final review?

openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label Aug 28, 2024

davidjoy requested review from arbrandes and brian-smith-tcril August 28, 2024 20:11

brian-smith-tcril reviewed Aug 28, 2024

View reviewed changes

davidjoy added 2 commits August 28, 2024 16:59

docs: Adding ADR to OEP-65 regarding frontend app migrations

8ecc9c0

docs: adding pull request link to OEP-65 ADR-0002

674581e

davidjoy force-pushed the djoy/oep-65-adr-0002 branch from 4f0e6c2 to 674581e Compare August 28, 2024 20:59

kdmccormick reviewed Sep 3, 2024

View reviewed changes

oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst Outdated Show resolved Hide resolved

davidjoy added 3 commits September 4, 2024 10:07

docs: fixing list/sub-list styling

cc5f2b7

docs: second draft of OEP-65 ADR 0002 on frontend app migrations

365b804

Also fixing a broken link in oep 65 and the title of ADR 0001, which doesn’t need to say “OEP-65” in it.

docs: OEP-65 ADR 0002 - adding a note about lack of version consistency.

024afd2

davidjoy requested a review from brian-smith-tcril September 4, 2024 15:23

itsjeyd added the waiting for eng review PR is ready for review. Review and merge it, or suggest changes. label Sep 7, 2024

davidjoy added 7 commits September 13, 2024 16:28

docs: Adding a frontend glossary for OEP-65.

eb8badf

Subsequent commits will start using this glossary via :term: roles.

docs: updating OEP-65 ADR-0002 to use the glossary

06600cb

Also linking out to other documents more liberally.

docs: adding ADR 0003 about Frontend Projects to OEP-65.

bbfa7da

docs: fixing a typo in the oep-0065 README

fe1c4b4

docs: Updating the language in OEP-65 ADR-0001 to match that of ADRs …

aa7e635

…2 and 3 This also liberally uses the glossary in the ADR.

docs: Updating OEP-65 to use the frontend glossary

aa43569

This commit updates the language of OEP-65 to match its three ADRs, and also makes use of the frontend glossary where possible. Many of the terms used in the glossary don’t actually come up in the OEP.

docs: Adding a new recommendation to OEP-65 around shared dependencies

42bd882

davidjoy changed the title ~~docs: Adding ADR to OEP-65 regarding frontend app migrations~~ docs: Adding ADRs 0002, 0003 and a glossary to OEP-65 Sep 13, 2024

arbrandes reviewed Sep 24, 2024

View reviewed changes

davidjoy added 3 commits September 24, 2024 15:35

docs: renaming “application module library” to “module library”

ae0fa32

docs: clarifying why site and module projects exist

36fd856

docs: clarifying a sentence

ef12337

davidjoy requested a review from arbrandes September 24, 2024 19:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Adding ADRs 0002, 0003 and a glossary to OEP-65 #626

docs: Adding ADRs 0002, 0003 and a glossary to OEP-65 #626

davidjoy commented Aug 28, 2024 •

edited

Loading

openedx-webhooks commented Aug 28, 2024

brian-smith-tcril left a comment

arbrandes left a comment

arbrandes Sep 24, 2024

arbrandes Sep 24, 2024

arbrandes Sep 24, 2024

davidjoy Sep 24, 2024

arbrandes Sep 24, 2024

arbrandes Sep 24, 2024

davidjoy Sep 24, 2024

arbrandes Sep 24, 2024

davidjoy Sep 24, 2024

arbrandes Sep 24, 2024

arbrandes Sep 24, 2024

davidjoy Sep 24, 2024

sarina commented Oct 16, 2024

davidjoy commented Oct 16, 2024

sarina commented Oct 21, 2024

		@@ -245,8 +248,12 @@ Process

		We need to ensure maintainers and developers know what dependency versions to use, and when they need to upgrade to stay consistent. Open edX release documentation should include information on which frontend dependency versions are compatible with the release, likely pinned to a major version (i.e., React 17.x, Paragon 22.x, etc.)

		Further, we recommend that each Open edX release have a single supported major version of all shared dependencies, and that all MFEs be upgraded to it prior to release.

	As we adopt ``frontend-base``, the libraries it replaces will undergo their own deprecation processes, which will need to coordinate with the migration of micro-frontends included in Open edX releases. After that deprecation, the micro-frontend architecture will cease to be supported.
	As we adopt ``frontend-base``, the libraries it replaces will undergo their own deprecation processes, which we'll need to coordinate with the migration of micro-frontends included in Open edX releases. After that deprecation, the micro-frontend architecture will cease to be supported.

	The ``dev``, ``dev:module``, ``build``, and ``build:module`` CLI commands will rely on the existence of a :term:`Site Config` file (the replacement for .env/env.config files) which will not be checked into the repository.
	The ``dev``, ``dev:module``, ``build``, and ``build:module`` CLI commands will rely on the existence of a :term:`Site Config` file (the replacement for .env/env.config files) which will not be checked into the module repository.


		Our definition of :term:`module` aligns with the `industry standard definition <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules>`_. It is also used in the context of `module federation <https://module-federation.io>`_. It's a self-contained part of the frontend that represents a specific part of the :term:`Site`, and can be loaded in a variety of ways. We have several sub-types of module:

		* An application module represents a well-bounded sub-area of the Open edX frontend at a particular route path. This might be "courseware", "the login page", or "account settings". There are a number of application modules that are required for a functioning Open edX frontend Site.


		Addressing our lack of dependency version consistency is one of the primary drivers of OEP-65.

		The shell will support specific versions of shared dependencies (such as React, Paragon, or React Router). All applications loaded into the shell's Site will be expected to use (or at least be compatible) with that version. We intend to create lock-step version consistency of shared dependencies across all applications in the platform. We envision each Open edX release supporting a particular major version of each shared dependency.

docs: Adding ADRs 0002, 0003 and a glossary to OEP-65 #626

Are you sure you want to change the base?

docs: Adding ADRs 0002, 0003 and a glossary to OEP-65 #626

Conversation

davidjoy commented Aug 28, 2024 • edited Loading

openedx-webhooks commented Aug 28, 2024

What's next?

🔘 Get product approval

🔘 Provide context

🔘 Get a green build

🔘 Let us know that your PR is ready for review:

Who will review my changes?

Where can I find more information?

When can I expect my changes to be merged?

brian-smith-tcril left a comment

Choose a reason for hiding this comment

arbrandes left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sarina commented Oct 16, 2024

davidjoy commented Oct 16, 2024

sarina commented Oct 21, 2024

davidjoy commented Aug 28, 2024 •

edited

Loading