From 8ecc9c0c059a0e3998942b790dd024b1f013c0eb Mon Sep 17 00:00:00 2001 From: David Joy Date: Wed, 28 Aug 2024 16:07:18 -0400 Subject: [PATCH 01/15] docs: Adding ADR to OEP-65 regarding frontend app migrations --- .../0002-frontend-app-migrations.rst | 119 ++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst diff --git a/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst b/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst new file mode 100644 index 000000000..7abb7c7a9 --- /dev/null +++ b/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst @@ -0,0 +1,119 @@ +OEP-65 Frontend App Migrations +############################## + +Status +****** + +Accepted + +Summary +******* + +This ADR describes a migration path and simplified repository organization for the frontend-app-* repositories that is compatible with the shell provided by frontend-base as well as module federation and frontend projects. + +Context +******* + +OEP-65 proposes adopting webpack module federation for Open edX micro-frontends (MFEs) as a means to enable *runtime module loading* and *shared dependencies* in the Open edX frontend. The OEP lays out a series of changes necessary to enable these capabilities, which it refers to as building a "reference implementation" of runtime module loading and shared dependencies. + +This reference implementation is effectively a new underlying architecture for our frontend. This ADR refers to this new architecture as the "module" architecture, as opposed to the historical "micro-frontend" architecture that has existed prior to OEP-65. + +As part of this paradigm shift, our frontend-app-* repositories (MFEs) will need to be migrated to work with frontend-base. Of particular note, this will require the repositories to: + +- Adopt a new set of build/development CLI helpers +- Use the shell to provide the header, footer, and runtime initialization code, amongst other things. +- Organize their code into loosely-coupled top-level components, which we'll call *modules*. + +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. + +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 Shell, deployed as a Site. We will document the migration process in detail. At a high level: + +- They will be deployable via a variety of methods, all of which will use the Shell. +- They will be deployable together or independently. +- They will no longer contain .env or env.config files for any environment, including Devstack and Tutor. +- They will cease to use the following libraries in favor of frontend-base: + - @openedx/frontend-build + - @edx/frontend-plaform + - @openedx/frontend-plugin-framework + - @edx/frontend-component-header + - @edx/frontend-component-footer + - @openedx/frontend-slot-footer + - @edx/brand + - core-js + - regenerator-runtime +- The following dependencies will become peer dependencies: + - @openedx/frontend-base + - @openedx/paragon + - react + - react-dom + - react-redux + - react-router + - react-router-dom + - redux +- They will replace the frontend-build ``fedx-scripts`` CLI tools with the frontend-base ``openedx`` CLI tools. 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. + - ``build`` will create a standalone deployable artifact that uses the shell (similar to the micro-frontend architecture) + - ``build:module`` will create a standalone deployable artifact that provides the application modules via module federation. + - ``release`` will package the library for distribution on npm. + - ``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 "Site Config" file (the replacement for .env/env.config files) which will not be checked into the repository. +- frontend-app-* repositories that are part of Open edX releases will be expected to be published on NPM as a library which exports its modules. + +Redefining "application" +======================== + +This decision constitutes a re-definition of "application" in the Open edX frontend ecosystem. In the past, "application" was synonymous with the entire frontend-app-* repository. With this ADR, "application" will be synonymous with the top-level modules provided by a frontend-app-* repository. Those modules are applications. + +We believe that the boundaries of our frontend-app-* repositories are fairly arbitrary and not as semantically meaningful as the boundaries of the *application modules* within them. We want these modules to be the primary unit of modularity - not the entire repository. The shell will be configured to load applications, not repositories. + +As an example: + +* The ``frontend-app-learning`` repository contains modules related to "learning" - course outline, courseware, the progress and dates pages, etc. +* The ``frontend-app-authn`` repository contains modules related to "authentication" - login, registration, logout, forgot password, etc. + +The shell will be configured to load things like "courseware" or "login", not "learning" and "authn" - the repository the module is in is incidental. + +Regarding "plugins" +------------------- + +Plugins are another type of module. We believe that they are different than application modules because they have a different interface with the shell. Plugins are generally UI widgets loaded into a slot, though some can be larger. Applications are generally large and complex, comprising multiple pages of functionality with internal routing. They are also loaded at a path in the application, not in a plugin slot. + +Modeling applications as Plugins is a possibility, but we believe that it feels like too much indirection and abstraction, and minimizes the importance of applications. Without them there's no site, and many are likely *required* functionality for the Open edX frontend to function at all. + +Some frontend-app-* repositories may also include Plugins, but they aren't the primary subject of this ADR. + +Consequences +************ + +As the module architecture stabilizes, frontend-app-* maintainers and developers will be encouraged to migrate their micro-frontends into application module libraries, and to adopt the module architecture provided by frontend-base. (There will be a migration guide.) + +As micro-frontends are migrated application modules using the shell, there will be a deployment approach that mimics the micro-frontend architecture, but which will require operators to adopt a new underlying configuration and build process to achieve a similar result. Each frontend-app-* repository will need a deprecation process for the micro-frontend configuration and build infrastructure. + +Unsupported Customizations +========================== + +The micro-frontend architecture took an extreme approach to "flexibility", allowing MFEs to diverge from each other in a variety of ways as described in OEP-65. As a result, in the process of migrating them to the module architecture, there could be unforeseen refactoring that may need to happen in some MFEs that don't map into modules well, or which have customizations that aren't supported by the Shell. While we hope to provide enough extensibility mechanisms to reduce the need for forking or hacky customizations, there will be customizations we haven't anticipated, which the community will need to work around or find ways to support. + +Consistent Dependency Versions +============================== + +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. + +References +********** + +* :doc:`OEP-65: Frontend Composability <../../oep-0065-arch-frontend-composability>` +* :doc:`ADR-0001: Unified Platform Repository <./0001-unified-platform-repository>` + +Change History +************** + +2024-08-28 +========== + +* Document created From 674581e0b051fc3f5a79cb806d20cddeade98ce4 Mon Sep 17 00:00:00 2001 From: David Joy Date: Wed, 28 Aug 2024 16:14:04 -0400 Subject: [PATCH 02/15] docs: adding pull request link to OEP-65 ADR-0002 --- .../oep-0065/decisions/0002-frontend-app-migrations.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst b/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst index 7abb7c7a9..dcabdcef6 100644 --- a/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst +++ b/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst @@ -117,3 +117,4 @@ Change History ========== * Document created +* `Pull request #626 `_ From cc5f2b70afa606666db0bd607bc9daeb912b0afb Mon Sep 17 00:00:00 2001 From: David Joy Date: Wed, 4 Sep 2024 10:07:24 -0400 Subject: [PATCH 03/15] docs: fixing list/sub-list styling --- .../0002-frontend-app-migrations.rst | 76 ++++++++++--------- 1 file changed, 41 insertions(+), 35 deletions(-) diff --git a/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst b/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst index dcabdcef6..2b93cd049 100644 --- a/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst +++ b/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst @@ -20,9 +20,9 @@ This reference implementation is effectively a new underlying architecture for o As part of this paradigm shift, our frontend-app-* repositories (MFEs) will need to be migrated to work with frontend-base. Of particular note, this will require the repositories to: -- Adopt a new set of build/development CLI helpers -- Use the shell to provide the header, footer, and runtime initialization code, amongst other things. -- Organize their code into loosely-coupled top-level components, which we'll call *modules*. +* Adopt a new set of build/development CLI helpers +* Use the shell to provide the header, footer, and runtime initialization code, amongst other things. +* Organize their code into loosely-coupled top-level components, which we'll call *modules*. 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. @@ -31,38 +31,44 @@ 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 Shell, deployed as a Site. We will document the migration process in detail. At a high level: -- They will be deployable via a variety of methods, all of which will use the Shell. -- They will be deployable together or independently. -- They will no longer contain .env or env.config files for any environment, including Devstack and Tutor. -- They will cease to use the following libraries in favor of frontend-base: - - @openedx/frontend-build - - @edx/frontend-plaform - - @openedx/frontend-plugin-framework - - @edx/frontend-component-header - - @edx/frontend-component-footer - - @openedx/frontend-slot-footer - - @edx/brand - - core-js - - regenerator-runtime -- The following dependencies will become peer dependencies: - - @openedx/frontend-base - - @openedx/paragon - - react - - react-dom - - react-redux - - react-router - - react-router-dom - - redux -- They will replace the frontend-build ``fedx-scripts`` CLI tools with the frontend-base ``openedx`` CLI tools. 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. - - ``build`` will create a standalone deployable artifact that uses the shell (similar to the micro-frontend architecture) - - ``build:module`` will create a standalone deployable artifact that provides the application modules via module federation. - - ``release`` will package the library for distribution on npm. - - ``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 "Site Config" file (the replacement for .env/env.config files) which will not be checked into the repository. -- frontend-app-* repositories that are part of Open edX releases will be expected to be published on NPM as a library which exports its modules. +* They will be deployable via a variety of methods, all of which will use the Shell. +* They will be deployable together or independently. +* They will no longer contain .env or env.config files for any environment, including Devstack and Tutor. +* They will cease to use the following libraries in favor of frontend-base: + + * @openedx/frontend-build + * @edx/frontend-plaform + * @openedx/frontend-plugin-framework + * @edx/frontend-component-header + * @edx/frontend-component-footer + * @openedx/frontend-slot-footer + * @edx/brand + * core-js + * regenerator-runtime + +* The following dependencies will become peer dependencies: + + * @openedx/frontend-base + * @openedx/paragon + * react + * react-dom + * react-redux + * react-router + * react-router-dom + * redux + +* They will replace the frontend-build ``fedx-scripts`` CLI tools with the frontend-base ``openedx`` CLI tools. 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. + * ``build`` will create a standalone deployable artifact that uses the shell (similar to the micro-frontend architecture) + * ``build:module`` will create a standalone deployable artifact that provides the application modules via module federation. + * ``release`` will package the library for distribution on npm. + * ``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 "Site Config" file (the replacement for .env/env.config files) which will not be checked into the repository. +* frontend-app-* repositories that are part of Open edX releases will be expected to be published on NPM as a library which exports its modules. Redefining "application" ======================== From 365b8045eb2331c1d52ba1c92ea7da2e1caaa106 Mon Sep 17 00:00:00 2001 From: David Joy Date: Wed, 4 Sep 2024 11:19:29 -0400 Subject: [PATCH 04/15] docs: second draft of OEP-65 ADR 0002 on frontend app migrations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Also fixing a broken link in oep 65 and the title of ADR 0001, which doesn’t need to say “OEP-65” in it. --- .../oep-0065-arch-frontend-composability.rst | 3 +- .../0001-unified-platform-repository.rst | 4 +- .../0002-frontend-app-migrations.rst | 123 ++++++++++-------- 3 files changed, 73 insertions(+), 57 deletions(-) diff --git a/oeps/architectural-decisions/oep-0065-arch-frontend-composability.rst b/oeps/architectural-decisions/oep-0065-arch-frontend-composability.rst index 0e599c725..c4712f53a 100644 --- a/oeps/architectural-decisions/oep-0065-arch-frontend-composability.rst +++ b/oeps/architectural-decisions/oep-0065-arch-frontend-composability.rst @@ -29,7 +29,8 @@ OEP-65: Frontend Composability * - References - * `FC-0054 - Composable Micro-frontends Discovery `_ * `FC-0007 - Modular MFE Domains Discovery `_ - * :doc:`ADR 0001 - Create a unified platform repository ` + * :doc:`ADR 0001 - Create a unified platform repository ` + * :doc:`ADR 0002 - Frontend app migrations ` .. contents:: :local: diff --git a/oeps/architectural-decisions/oep-0065/decisions/0001-unified-platform-repository.rst b/oeps/architectural-decisions/oep-0065/decisions/0001-unified-platform-repository.rst index 1e8c00270..aed55bed3 100644 --- a/oeps/architectural-decisions/oep-0065/decisions/0001-unified-platform-repository.rst +++ b/oeps/architectural-decisions/oep-0065/decisions/0001-unified-platform-repository.rst @@ -1,5 +1,5 @@ -OEP-65 Create a unified platform repository -########################################### +Create a unified platform repository +#################################### Status ****** diff --git a/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst b/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst index 2b93cd049..4a43d8b0e 100644 --- a/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst +++ b/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst @@ -1,5 +1,5 @@ -OEP-65 Frontend App Migrations -############################## +Frontend App Migrations +####################### Status ****** @@ -9,7 +9,7 @@ Accepted Summary ******* -This ADR describes a migration path and simplified repository organization for the frontend-app-* repositories that is compatible with the shell provided by frontend-base as well as module federation and frontend projects. +This ADR describes a migration path and simplified repository organization for the frontend-app-* repositories that is compatible with the shell provided by frontend-base, module federation, and frontend projects. Context ******* @@ -18,87 +18,102 @@ OEP-65 proposes adopting webpack module federation for Open edX micro-frontends This reference implementation is effectively a new underlying architecture for our frontend. This ADR refers to this new architecture as the "module" architecture, as opposed to the historical "micro-frontend" architecture that has existed prior to OEP-65. -As part of this paradigm shift, our frontend-app-* repositories (MFEs) will need to be migrated to work with frontend-base. Of particular note, this will require the repositories to: +As part of this paradigm shift, our ``frontend-app-*`` repositories (MFEs) will need to be migrated to work with `frontend-base `_. Of particular note, this will require the repositories to: * Adopt a new set of build/development CLI helpers * Use the shell to provide the header, footer, and runtime initialization code, amongst other things. -* Organize their code into loosely-coupled top-level components, which we'll call *modules*. +* Organize their code into loosely-coupled top-level components, which we'll call *application modules*. -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 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. 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 Shell, deployed as a Site. We will document the migration process in detail. At a high level: +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 Shell, deployed as a Site. These are called *application module libraries*. We will document the migration process in detail. At a high level, this will involve the following changes. -* They will be deployable via a variety of methods, all of which will use the Shell. -* They will be deployable together or independently. -* They will no longer contain .env or env.config files for any environment, including Devstack and Tutor. -* They will cease to use the following libraries in favor of frontend-base: +New Deployment Methods +====================== - * @openedx/frontend-build - * @edx/frontend-plaform - * @openedx/frontend-plugin-framework - * @edx/frontend-component-header - * @edx/frontend-component-footer - * @openedx/frontend-slot-footer - * @edx/brand - * core-js - * regenerator-runtime +The application module libraries will be buildable in several different ways. -* The following dependencies will become peer dependencies: +* Built as an independent Site using the Shell for initialization, the header and footer, configuration, and other foundational services (logging, analytics, i18n, etc.) +* Built as federated modules to be loaded into the Shell at runtime via webpack module federation. +* Built and released as an NPM package for build-time inclusion in a frontend Project, perhaps alongside other application modules from other libraries. - * @openedx/frontend-base - * @openedx/paragon - * react - * react-dom - * react-redux - * react-router - * react-router-dom - * redux +Environment Agnostic +==================== -* They will replace the frontend-build ``fedx-scripts`` CLI tools with the frontend-base ``openedx`` CLI tools. We'll discuss some of them in detail here, as they help illustrate what the library will be able to do: +The application module libraries will no longer contain ``.env`` or ``env.config`` files for any specific environment, including Devstack and Tutor. Config filename patterns will be added to the ``.gitignore`` file. They will continue to support adding a (git ignored) config file into the repository to build or develop it, but we also expect operators to use Projects and check their config files into those project repositories as their primary way of working with the application module libraries. - * ``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. - * ``build`` will create a standalone deployable artifact that uses the shell (similar to the micro-frontend architecture) - * ``build:module`` will create a standalone deployable artifact that provides the application modules via module federation. - * ``release`` will package the library for distribution on npm. - * ``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) +Projects and these config files will be the subject of a subsequent ADR. -* The ``dev``, ``dev:module``, ``build``, and ``build:module`` CLI commands will rely on the existence of a "Site Config" file (the replacement for .env/env.config files) which will not be checked into the repository. -* frontend-app-* repositories that are part of Open edX releases will be expected to be published on NPM as a library which exports its modules. +Removed Dependencies +==================== -Redefining "application" -======================== +Application module libraries will cease to use the following libraries in favor of ``frontend-base``: -This decision constitutes a re-definition of "application" in the Open edX frontend ecosystem. In the past, "application" was synonymous with the entire frontend-app-* repository. With this ADR, "application" will be synonymous with the top-level modules provided by a frontend-app-* repository. Those modules are applications. +* @openedx/frontend-build +* @edx/frontend-plaform +* @openedx/frontend-plugin-framework +* @edx/frontend-component-header +* @edx/frontend-component-footer +* @openedx/frontend-slot-footer +* @edx/brand +* core-js +* regenerator-runtime -We believe that the boundaries of our frontend-app-* repositories are fairly arbitrary and not as semantically meaningful as the boundaries of the *application modules* within them. We want these modules to be the primary unit of modularity - not the entire repository. The shell will be configured to load applications, not repositories. +Peer Dependencies +================= -As an example: +We expect application module libraries to be dependencies of Frontend Projects by default for most operators. Because of this, the following dependencies will become peer dependencies in the application module libraries themselves: -* The ``frontend-app-learning`` repository contains modules related to "learning" - course outline, courseware, the progress and dates pages, etc. -* The ``frontend-app-authn`` repository contains modules related to "authentication" - login, registration, logout, forgot password, etc. +* @openedx/frontend-base +* @openedx/paragon +* react +* react-dom +* react-redux +* react-router +* react-router-dom +* redux -The shell will be configured to load things like "courseware" or "login", not "learning" and "authn" - the repository the module is in is incidental. +New CLI Tools +============= -Regarding "plugins" -------------------- +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: -Plugins are another type of module. We believe that they are different than application modules because they have a different interface with the shell. Plugins are generally UI widgets loaded into a slot, though some can be larger. Applications are generally large and complex, comprising multiple pages of functionality with internal routing. They are also loaded at a path in the application, not in a plugin slot. +* ``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. +* ``build`` will create a standalone deployable artifact that uses the shell (similar to the micro-frontend architecture) +* ``build:module`` will create a standalone deployable artifact that provides the application modules via module federation. +* ``release`` will package the library for distribution on npm. +* ``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) -Modeling applications as Plugins is a possibility, but we believe that it feels like too much indirection and abstraction, and minimizes the importance of applications. Without them there's no site, and many are likely *required* functionality for the Open edX frontend to function at all. +The ``dev``, ``dev:module``, ``build``, and ``build:module`` CLI commands will rely on the existence of a "Site Config" file (the replacement for .env/env.config files) which will not be checked into the repository. -Some frontend-app-* repositories may also include Plugins, but they aren't the primary subject of this ADR. +Distributed as NPM Packages +=========================== + +``frontend-app-*`` repositories that are part of Open edX releases will be expected to be published on NPM as a library which exports its modules. These libraries will primarily be consumed by Frontend Projects. Consequences ************ -As the module architecture stabilizes, frontend-app-* maintainers and developers will be encouraged to migrate their micro-frontends into application module libraries, and to adopt the module architecture provided by frontend-base. (There will be a migration guide.) +As the module architecture stabilizes, ``frontend-app-*`` maintainers and developers will be encouraged to migrate their micro-frontends into application module libraries, and to adopt the module architecture provided by ``frontend-base``. (There will be a migration guide.) + +As micro-frontends are migrated to application module libraries using the shell, there will be a deployment approach that mimics the micro-frontend architecture, but which will require operators to adopt a new underlying configuration and build process to achieve a similar result. Each ``frontend-app-*`` repository will need a deprecation process for the micro-frontend configuration and build infrastructure. + +Thinking in Modules +=================== + +Our definition of "module" aligns with the `industry standard definition `_. It is also used in the context of `module federation `_. It's a self-contained part of the frontend that represents a specific part of the 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 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. +* A "plugin module" represents an optional UI component that is generally added somewhere in an application module, or in the shell. The header and footer, for instance, would be overridden with alternate implementations via plugin modules. New tabs added to the course homepage are also plugin modules. +* *Service modules* which act as implementations of the logging or analytics services. +* *Script modules* which allow attaching arbitrary scripts to the page. -As micro-frontends are migrated application modules using the shell, there will be a deployment approach that mimics the micro-frontend architecture, but which will require operators to adopt a new underlying configuration and build process to achieve a similar result. Each frontend-app-* repository will need a deprecation process for the micro-frontend configuration and build infrastructure. +Our ``frontend-app-*`` repositories go from being "micro-frontend applications" to being a collection of application modules centered around a particular domain (learning, authoring, authn, etc.) The question of which application modules belong in which repositories, and where the right boundaries are, is beyond the scope of this ADR. Unsupported Customizations ========================== From 024afd230d4f19d0f9f9cdb473d373e3c66cc019 Mon Sep 17 00:00:00 2001 From: David Joy Date: Wed, 4 Sep 2024 11:22:04 -0400 Subject: [PATCH 05/15] docs: OEP-65 ADR 0002 - adding a note about lack of version consistency. --- .../oep-0065/decisions/0002-frontend-app-migrations.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst b/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst index 4a43d8b0e..8a86a94ae 100644 --- a/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst +++ b/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst @@ -123,6 +123,8 @@ The micro-frontend architecture took an extreme approach to "flexibility", allow Consistent Dependency Versions ============================== +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. References From eb8badf55beafa4709440b4b918e2276f92d6dc9 Mon Sep 17 00:00:00 2001 From: David Joy Date: Fri, 13 Sep 2024 16:25:46 -0400 Subject: [PATCH 06/15] docs: Adding a frontend glossary for OEP-65. Subsequent commits will start using this glossary via :term: roles. --- .../oep-0065-arch-frontend-composability.rst | 1 + .../0001-unified-platform-repository.rst | 1 + .../0002-frontend-app-migrations.rst | 1 + .../oep-0065/decisions/frontend-glossary.rst | 149 ++++++++++++++++++ 4 files changed, 152 insertions(+) create mode 100644 oeps/architectural-decisions/oep-0065/decisions/frontend-glossary.rst diff --git a/oeps/architectural-decisions/oep-0065-arch-frontend-composability.rst b/oeps/architectural-decisions/oep-0065-arch-frontend-composability.rst index c4712f53a..eae6baaa1 100644 --- a/oeps/architectural-decisions/oep-0065-arch-frontend-composability.rst +++ b/oeps/architectural-decisions/oep-0065-arch-frontend-composability.rst @@ -31,6 +31,7 @@ OEP-65: Frontend Composability * `FC-0007 - Modular MFE Domains Discovery `_ * :doc:`ADR 0001 - Create a unified platform repository ` * :doc:`ADR 0002 - Frontend app migrations ` + * :doc:`OEP-65 Frontend Glossary ` .. contents:: :local: diff --git a/oeps/architectural-decisions/oep-0065/decisions/0001-unified-platform-repository.rst b/oeps/architectural-decisions/oep-0065/decisions/0001-unified-platform-repository.rst index aed55bed3..74a16c133 100644 --- a/oeps/architectural-decisions/oep-0065/decisions/0001-unified-platform-repository.rst +++ b/oeps/architectural-decisions/oep-0065/decisions/0001-unified-platform-repository.rst @@ -123,6 +123,7 @@ References ********** * :doc:`OEP-65: Frontend Composability <../../oep-0065-arch-frontend-composability>` +* :doc:`OEP-65 Frontend Glossary <./frontend-glossary>` Change History ************** diff --git a/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst b/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst index 8a86a94ae..44cd2e3fc 100644 --- a/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst +++ b/oeps/architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations.rst @@ -131,6 +131,7 @@ References ********** * :doc:`OEP-65: Frontend Composability <../../oep-0065-arch-frontend-composability>` +* :doc:`OEP-65 Frontend Glossary <./frontend-glossary>` * :doc:`ADR-0001: Unified Platform Repository <./0001-unified-platform-repository>` Change History diff --git a/oeps/architectural-decisions/oep-0065/decisions/frontend-glossary.rst b/oeps/architectural-decisions/oep-0065/decisions/frontend-glossary.rst new file mode 100644 index 000000000..638a32817 --- /dev/null +++ b/oeps/architectural-decisions/oep-0065/decisions/frontend-glossary.rst @@ -0,0 +1,149 @@ +Frontend Glossary +################# + +High Level Concepts +******************* + +.. glossary:: + + Application Module Library + Application module libraries are a collection of related modules co-located in a repository together (``frontend-app-*``) in the :term:`Module Architecture`. As an example, a library might be named ``frontend-app-learning``, and it would contain modules such as courseware, course outline, progress page, and dates page. + + Note that this stands in contrast to how the ``frontend-app-*`` repositories were used in the :term:`Micro-frontend Architecture`. + + Guest + A Guest is the :term:`Module` being loaded into a :term:`Site` via module federation. + + Host + A Host is the :term:`Site` loading a :term:`Module` via module federation. + + Micro-frontend + Micro-frontend is an industry standard term for small, composable, independently deployed pieces of a frontend. It has a specific and narrower meaning in Open edX's frontend. Open edX's decoupled frontend architecture has been called the "micro-frontend architecture" since 2018 or so, and the ``frontend-app-*`` repositories, specifically, are referred to as "micro-frontends" or "MFEs" for short. They're often called "micro-frontend applications" as well. Some might argue it's a misnomer, as many of our MFEs are quite large. Regardless, MFEs in Open edX refer to our independently deployed, siloed frontends which do not share dependencies, and which may contain one or more distinct parts of the overall frontend. + + To support a cohesive vernacular for our post-MFE architecture (The "module" architecture?), we propose co-opting "micro-frontend" and "application" to refer to a sub-type of modules - :term:`application modules `. Each of the ``frontend-app-*`` repositories is really a collection of related micro-frontend applications co-located in the repository together because they share code and dependencies unique to their domain. For instance, the "learning" MFE - course outline, courseware, progress page, dates page, etc. - share a significant amount of code, but may be better thought of as a collection of related apps, not as "the learning app". + + The rest of this glossary reflects the proposed usage of "application". + + Micro-frontend Architecture + This is the name for the Open edX frontend architecture based on ``frontend-platform``, ``frontend-build``, and independent ``frontend-app-*`` repositories that represent :term:`micro-frontends `. It has been super-ceded by the :term:`Module Architecture`. + + Module + A piece of code that provides some specific, tightly coupled functionality, and which is loaded into a :term:`Site` via one of several loading mechanisms (:term:`Imported Module`, :term:`Federated Module`, or :term:`Linked Module`) which can happen at buildtime or runtime. + + There are different sub-types of modules, such as :term:`Applications `, :term:`Plugins `, :term:`Services `, or :term:`Scripts