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.

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

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?

arbrandes

Apologies for the delay, but definitely approved now!

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

arbrandes approved these changes Nov 5, 2024

View reviewed changes

arbrandes merged commit b6e7291 into openedx:master Nov 5, 2024
5 checks passed

davidjoy deleted the djoy/oep-65-adr-0002 branch November 5, 2024 17:40

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

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

sarina commented Oct 16, 2024

davidjoy commented Oct 16, 2024

sarina commented Oct 21, 2024

arbrandes left a comment

		@@ -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.

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

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

sarina commented Oct 16, 2024

davidjoy commented Oct 16, 2024

sarina commented Oct 21, 2024

arbrandes left a comment

Choose a reason for hiding this comment

davidjoy commented Aug 28, 2024 •

edited

Loading