From ae0fa3259d5e09878176267751dc91a458ce435c Mon Sep 17 00:00:00 2001 From: David Joy Date: Tue, 24 Sep 2024 15:35:40 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20renaming=20=E2=80=9Capplication=20modul?= =?UTF-8?q?e=20library=E2=80=9D=20to=20=E2=80=9Cmodule=20library=E2=80=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../0002-frontend-app-migrations.rst | 24 +++++++++---------- .../decisions/0003-frontend-projects.rst | 6 ++--- .../oep-0065/decisions/frontend-glossary.rst | 14 +++++------ 3 files changed, 22 insertions(+), 22 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 6b2d6ff30..764fbb4f4 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 @@ -31,21 +31,21 @@ As we adopt ``frontend-base``, the libraries it replaces will undergo their own 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 `. We will document the migration process in detail. At a high level, this will involve the following changes. +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:`module libraries `. We will document the migration process in detail. At a high level, this will involve the following changes. New Deployment Methods ====================== -The application module libraries will be buildable in several different ways. +The module libraries will be buildable in several different ways. * Built as :term:`imported modules ` into an independent Site using the Shell for initialization, the header and footer, configuration, and other foundational services (logging, analytics, i18n, etc.) * Built as :term:`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 :term:`Project`, perhaps alongside other application modules from other libraries. +* Built and released as an NPM package for build-time inclusion in a frontend :term:`Project`, perhaps alongside other modules from other libraries. Environment Agnostic ==================== -The :term:`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. +The :term:`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 module libraries. Please see :doc:`0003-frontend-projects` for more information on projects. @@ -67,7 +67,7 @@ Application module libraries will cease to use the following libraries in favor Peer Dependencies ================= -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: +We expect 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 module libraries themselves: * @openedx/frontend-base * @openedx/paragon @@ -83,15 +83,15 @@ New CLI Tools 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. +* ``dev`` will start a dev server, loading the repository's modules into the shell in a site. +* ``dev:module`` will start a dev server that provides the 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. +* ``build:module`` will create a standalone deployable artifact that provides the 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 :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 library's repository. Distributed as NPM Packages =========================== @@ -101,9 +101,9 @@ Distributed as NPM Packages 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 module libraries, and to adopt the module architecture provided by ``frontend-base``. (There will be a migration guide.) -For micro-frontends that 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. +For micro-frontends that are migrated to 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 =================== @@ -115,7 +115,7 @@ Our definition of :term:`module` aligns with the `industry standard definition < * *Service modules* which act as implementations of the logging or analytics services. * *Script modules* which allow attaching arbitrary scripts to the page. -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. +Our ``frontend-app-*`` repositories go from being "micro-frontend applications" to being a collection of modules centered around a particular domain (learning, authoring, authn, etc.) The question of which modules belong in which repositories, and where the right boundaries are, is beyond the scope of this ADR. Unsupported Customizations ========================== diff --git a/oeps/architectural-decisions/oep-0065/decisions/0003-frontend-projects.rst b/oeps/architectural-decisions/oep-0065/decisions/0003-frontend-projects.rst index 6569548f0..13bdf554d 100644 --- a/oeps/architectural-decisions/oep-0065/decisions/0003-frontend-projects.rst +++ b/oeps/architectural-decisions/oep-0065/decisions/0003-frontend-projects.rst @@ -69,7 +69,7 @@ Module Projects .. image:: ../module-project-architecture.png -A Module Project uses a ``config`` data structure in ``package.json`` to define what modules it should bundle for :term:`module federation`. This mirrors the ``config`` data structure in the :term:`application module libraries ` (``frontend-app-*`` repositories). It also uses a :term:`Module Config` file for additional configuration of those modules beyond that which will be supplied by the site's :term:`Site Config`, i.e., module-specific configuration. +A Module Project uses a ``config`` data structure in ``package.json`` to define what modules it should bundle for :term:`module federation`. This mirrors the ``config`` data structure in the :term:`module libraries ` (``frontend-app-*`` repositories). It also uses a :term:`Module Config` file for additional configuration of those modules beyond that which will be supplied by the site's :term:`Site Config`, i.e., module-specific configuration. To describe the steps in the above image: @@ -95,7 +95,7 @@ To describe the steps in the above image: 5. Webpack builds :term:`federated modules ` from the ``src`` based on the above configuration in ``package.json``. 6. The modules will be responsible for importing module-specific configuration from a :term:`Module Config` file. -7. The federated modules in ``src`` may be custom modules, or "pass-through" modules that re-export :term:`application modules ` from one of the project's dependencies. Note that webpack module federation cannot export modules from dependencies directly; a thin shim module is required (unfortunately). +7. The federated modules in ``src`` may be custom modules, or "pass-through" modules that re-export :term:`modules ` from one of the project's dependencies. Note that webpack module federation cannot export modules from dependencies directly; a thin shim module is required (unfortunately). This will function the same for all module sub-types. Implicit Projects ================= @@ -109,7 +109,7 @@ Fundamentally, site and module projects consist of: This means that any repository that satisfies these requirements can act as a project. These are :term:`"implicit" projects `. -Of particular note, ``frontend-app-*`` repositories will satisfy these requirements if we add a git-ignored Site Config or Module Config file to them, and in fact, we anticipate this will be a desirable way to do local development on application module libraries. +Of particular note, ``frontend-app-*`` repositories will satisfy these requirements if we add a git-ignored Site Config or Module Config file to them, and in fact, we anticipate this will be a desirable way to do local development on module libraries. Consequences ************ diff --git a/oeps/architectural-decisions/oep-0065/decisions/frontend-glossary.rst b/oeps/architectural-decisions/oep-0065/decisions/frontend-glossary.rst index 638a32817..2b0ef6198 100644 --- a/oeps/architectural-decisions/oep-0065/decisions/frontend-glossary.rst +++ b/oeps/architectural-decisions/oep-0065/decisions/frontend-glossary.rst @@ -6,11 +6,6 @@ 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. @@ -20,7 +15,7 @@ High Level Concepts 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". + To support a cohesive vernacular for our post-MFE architecture (the :term:`Module Architecture`), we propose co-opting "application" to refer to a sub-type of modules - :term:`application modules `. Each of the ``frontend-app-*`` repositories is really a collection of related applications co-located in the repository together because they share code and dependencies unique to their domain. For instance, the modules in 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". @@ -41,6 +36,11 @@ High Level Concepts Module Federation Module federation is a method that allows separate JavaScript builds to share code at runtime, forming a single application, while maintaining build and deployment independence. While not specific to Webpack, the initial `implementation of module federation `_ is in Webpack. + Module Library + 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. A module library may contain :term:`Modules ` of all different subtypes. + + Note that this stands in contrast to how the ``frontend-app-*`` repositories were used in the :term:`Micro-frontend Architecture`. + Open edX Frontend The complete set of interfaces shown to a user of an Open edX instance. Includes at least one independently deployed :term:`Site` and zero or more :term:`Federated Modules `. @@ -96,7 +96,7 @@ Related: See :term:`Module` in the `High Level Concepts`_ section. Application Module A sub-type of :term:`Module` that represents a logical portion of the UI of a :term:`Site`. A ``frontend-app-*`` repository will contain one or more application modules. - Applications are generally loaded at a path within a :term:`Site`, such as ``/learning`` or ``/profile``. They are a specialized kind of :term:`Module` fulfilling a core function of the :term:`Open edX Frontend`. They are known, registered entities, and other :term:`Modules ` can query the :term:`Shell` configuration to locate, navigate, or interact with them. + Application Modules are loaded at a path within a :term:`Site`, such as ``/learning`` or ``/profile``. They are a specialized kind of :term:`Module` fulfilling a core function of the :term:`Open edX Frontend`. They are known, registered entities, and other :term:`Modules ` can query the :term:`Shell` configuration to locate, navigate, or interact with them. Plugin Module A plugin is a :term:`Module` that adheres to the rules of the frontend plugin framework. Plugins are optional and must be loaded into a :term:`Plugin Slot`.