Docs: Add npm dependency conflict in troubleshooting section #200

hinakhadim · 2024-04-02T06:12:41Z

As community members face npm dependency conflict issue when overriding header and footer, here I list down the points on how to resolve it. Then, include the link of this section in tutor core

DawoudSheraz · 2024-04-02T10:00:34Z

README.rst

+When there is a need to customize the ``@edx/frontend-component-header`` or ``@edx/frontend-component-footer`` component, two things we have to care of to avoid dependency conflict error during ``npm`` installation. 
+
+1. Identify your openedx version, for example ``quince``.
+2. Navigate to `learning <https://github.com/openedx/frontend-app-learning>`_ and `learner-dashboard <https://github.com/openedx/frontend-app-learner-dashboard>`_ MFEs repositories and checkout to branch ``open-release/quince.master``. Inspect which header and footer versions are installed from ``package.json``. You can explore the header and footer versions for additional MFEs to ensure that all MFEs support the same major versions of header and footer. 


point 2 makes it seem like we are only focusing on learning and learner-dashboard MFE. The additional MFEs part does not stick. Maybe we can re-word this to focus that this applies to all MFEs but learning MFEs carry the most weight?

DawoudSheraz · 2024-04-09T06:21:58Z

README.rst

+7. Repeat the same process for customizing the footer component if necessary.
+
+


nit: can you add a stripped down version of example table you had on Google sheets? Visualizations help in conveying the message quickly.

DawoudSheraz · 2024-04-09T06:22:53Z

README.rst

+NPM Dependency Conflict When overriding ``@edx/frontend-component-header`` or ``@edx/frontend-component-footer``
+----------------------------------------------------------------------------------------------------------------
+
+When there is a need to customize the ``@edx/frontend-component-header`` or ``@edx/frontend-component-footer`` component, two things we have to care of to avoid dependency conflict error during ``npm`` installation. 


not necessarily two things here.

DawoudSheraz · 2024-04-17T07:04:06Z

README.rst

+NPM Dependency Conflict When overriding ``@edx/frontend-component-header`` or ``@edx/frontend-component-footer``
+----------------------------------------------------------------------------------------------------------------
+
+When there is a need to customize the ``@edx/frontend-component-header`` or ``@edx/frontend-component-footer`` component, it is necessary to address a crucial concerns to prevent dependency conflict errors during ``npm`` installation.. 


nit: a crucial concern

DawoudSheraz · 2024-04-17T07:04:27Z

README.rst

+
+When there is a need to customize the ``@edx/frontend-component-header`` or ``@edx/frontend-component-footer`` component, it is necessary to address a crucial concerns to prevent dependency conflict errors during ``npm`` installation.. 
+
+1. Identify your openedx version, for example ``quince``.


nit: for example,

DawoudSheraz · 2024-04-17T07:05:30Z

README.rst

+2. Navigate to `learning <https://github.com/openedx/frontend-app-learning>`_ and `learner-dashboard <https://github.com/openedx/frontend-app-learner-dashboard>`_ MFEs repositories and checkout to branch ``open-release/quince.master``. Inspect which header and footer versions are installed from ``package.json``. This can also be applied to all MFEs to ensure consistency of versions but Learning and Learner Dashboard MFE carry the most weight.
+3. Determine which versions of ``@edx/frontend-platform`` MFEs are utilizing and the header you plan to customize is compatible with the same version of ``@edx/frontend-platform`` specified in ``package.json`` file (peer-dependencies).
+4. Ensure consistency between the versions. For example, If MFE has ``@edx/frontend-platform: 7.0.1``, then customize the header component which has ``@edx/frontend-platform: ^7.0.0`` in ``package.json`` under peer-dependencies
+5. Checkout to that specific tag (e.g: ``v7.0.0``) of header component and customize it


nit: header/footer component

DawoudSheraz · 2024-04-17T07:06:26Z

README.rst

+4. Ensure consistency between the versions. For example, If MFE has ``@edx/frontend-platform: 7.0.1``, then customize the header component which has ``@edx/frontend-platform: ^7.0.0`` in ``package.json`` under peer-dependencies
+5. Checkout to that specific tag (e.g: ``v7.0.0``) of header component and customize it
+6. Install the customized header/footer components into your MFEs. This will resolve any npm dependency conflict issues.
+7. Repeat the same process for customizing the footer component if necessary.


nit: footer/header (considering in steps 1-6, we are using header/footer on various places, it is good to have the reverse in here).

DawoudSheraz · 2024-04-17T07:07:21Z

README.rst

+.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/screenshots/npm-conflict-deps.png
+    :alt: Observation of MFE header and footer versions
+
+From the above image, it can be observed that ``master`` branch of Learning MFE uses ``@edx/[email protected]`` and Discussoins MFE uses ``@edx/[email protected]``. If customized header is created from ``master`` branch, it ensures compatibility with the Discussions MFE as header module supports ``@edx/platform@^7.0.0``. However, The customized header triggers npm dependencies conflit error for learning MFE. 


Discussoins --> Discussions

DawoudSheraz · 2024-04-17T07:07:48Z

README.rst

+.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/screenshots/npm-conflict-deps.png
+    :alt: Observation of MFE header and footer versions
+
+From the above image, it can be observed that ``master`` branch of Learning MFE uses ``@edx/[email protected]`` and Discussoins MFE uses ``@edx/[email protected]``. If customized header is created from ``master`` branch, it ensures compatibility with the Discussions MFE as header module supports ``@edx/platform@^7.0.0``. However, The customized header triggers npm dependencies conflit error for learning MFE. 


However, The customized --> However, the customized

DawoudSheraz · 2024-04-17T07:08:53Z

README.rst

+In this case, checkout custom branch from ``v4.11.1`` of header for Learning MFE and ``v5.0.0`` for Discussions MFE.
+


We can add more context to explain how these versions will work in build.

DawoudSheraz · 2024-04-29T11:40:23Z

README.rst

+4. Ensure consistency between the versions. For example, If MFE has ``@edx/frontend-platform: 7.0.1``, then customize the header/footer component which has ``@edx/frontend-platform: ^7.0.0`` in ``package.json`` under peer-dependencies
+5. Checkout to that specific tag (e.g: ``v7.0.0``) of header component and customize it
+6. Install the customized header/footer components into your MFEs. This will resolve any npm dependency conflict issues.
+7. All the steps outlined above need to be followed for the footer as well, if you have followed them for the header


nit: add or vice versa at the end.

DawoudSheraz · 2024-04-30T13:19:23Z

README.rst

+NPM Dependency Conflict When overriding ``@edx/frontend-component-header`` or ``@edx/frontend-component-footer``
+----------------------------------------------------------------------------------------------------------------
+
+When there is a need to customize the ``@edx/frontend-component-header`` or ``@edx/frontend-component-footer`` component, it is necessary to address crucial concerns to prevent dependency conflict errors during ``npm`` installation.


it is necessary to address crucial concerns to prevent dependency conflict errors during ``npm`` installation.
☝🏽 this sentence can be removed and instead, something along the lines of there is a chance that npm dependency conflicts can occur. In the case of such a conflict, perform the following to resolve the conflicts while keeping the customizations in place:

DawoudSheraz · 2024-04-30T13:23:13Z

README.rst

+When there is a need to customize the ``@edx/frontend-component-header`` or ``@edx/frontend-component-footer`` component, it is necessary to address crucial concerns to prevent dependency conflict errors during ``npm`` installation.
+
+1. Identify your openedx version, for example, ``quince``.
+2. Navigate to `learning <https://github.com/openedx/frontend-app-learning>`_ and `learner-dashboard <https://github.com/openedx/frontend-app-learner-dashboard>`_ MFEs repositories and checkout to branch ``open-release/quince.master``. Inspect which header and footer versions are installed from ``package.json``. This can also be applied to all MFEs to ensure consistency of versions but Learning and Learner Dashboard MFE carry the most weight.


nit: Learning and Learner Dashboard MFEs

While I remember I suggested mentioning Learner and learning MFEs carry the most weight (being learner-facing), it looks out of place context-wise. Maybe this can be re-written to point out that learner MFEs are mentioned only as an example. The step can be applied to all MFEs.

DawoudSheraz · 2024-04-30T13:24:30Z

README.rst

+
+1. Identify your openedx version, for example, ``quince``.
+2. Navigate to `learning <https://github.com/openedx/frontend-app-learning>`_ and `learner-dashboard <https://github.com/openedx/frontend-app-learner-dashboard>`_ MFEs repositories and checkout to branch ``open-release/quince.master``. Inspect which header and footer versions are installed from ``package.json``. This can also be applied to all MFEs to ensure consistency of versions but Learning and Learner Dashboard MFE carry the most weight.
+3. Determine which versions of ``@edx/frontend-platform`` MFEs are utilizing and the header/footer you plan to customize is compatible with the same version of ``@edx/frontend-platform`` specified in ``package.json`` file (peer-dependencies).


small nit: MFEs are utilizing and the header/footer ...

☝🏽 and looks a bit out of place in the sentence. This can be broken down into two sentences.

arbrandes

Thanks for adding this! I defer to @DawoudSheraz's comments, otherwise.

DawoudSheraz · 2024-05-10T07:29:24Z

README.rst

+6. Install the customized header/footer components into your MFEs. This will resolve any npm dependency conflict issues.
+7. All the steps outlined above need to be followed for the footer as well, if you have followed them for the header or vice versa.
+
+.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/screenshots/npm-conflict-deps.png


nit: instead of screenshots, let's name the directory media, content, or something along these lines. screenshots is a very specific term.

…t MFEs

DawoudSheraz · 2024-05-21T06:00:28Z

@hinakhadim does this require further action? Thanks

hinakhadim · 2024-05-21T06:05:09Z

Thanks for asking. I have made all improvements and no further action is reqiured.

DawoudSheraz · 2024-05-27T07:50:46Z

@arbrandes Hi, can you take another look at this? Thanks

hinakhadim requested review from arbrandes and regisb April 2, 2024 06:13

hinakhadim mentioned this pull request Apr 2, 2024

Add MFE related issues fixes in troubleshooting.html overhangio/tutor#1019

Closed

DawoudSheraz reviewed Apr 2, 2024

View reviewed changes

DawoudSheraz reviewed Apr 9, 2024

View reviewed changes

DawoudSheraz self-requested a review April 16, 2024 09:07

DawoudSheraz reviewed Apr 17, 2024

View reviewed changes

DawoudSheraz reviewed Apr 29, 2024

View reviewed changes

DawoudSheraz reviewed Apr 30, 2024

View reviewed changes

arbrandes reviewed May 1, 2024

View reviewed changes

DawoudSheraz self-requested a review May 7, 2024 09:07

DawoudSheraz reviewed May 10, 2024

View reviewed changes

DawoudSheraz approved these changes May 10, 2024

View reviewed changes

hinakhadim added 6 commits May 13, 2024 10:55

docs: add npm dependency conflict in troubleshooting section

edb13a8

docs: update second point

9445f8f

fix: add image reference for better clarity

40fca26

fix: add step for installing different versions of header in differen…

dd074b3

…t MFEs

fix: update readme

70d4ec6

fix: Rename screenshots folder to media

b72a6b5

hinakhadim force-pushed the hina/update-troubleshooting branch from a9ba1da to b72a6b5 Compare May 13, 2024 05:56

DawoudSheraz requested a review from arbrandes May 21, 2024 06:14

DawoudSheraz merged commit 15a0c6b into overhangio:master Jun 4, 2024
2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Add npm dependency conflict in troubleshooting section #200

Docs: Add npm dependency conflict in troubleshooting section #200

hinakhadim commented Apr 2, 2024 •

edited

Loading

DawoudSheraz Apr 2, 2024

hinakhadim Apr 5, 2024

DawoudSheraz Apr 9, 2024

DawoudSheraz Apr 9, 2024

DawoudSheraz Apr 17, 2024

DawoudSheraz Apr 17, 2024

DawoudSheraz Apr 17, 2024

DawoudSheraz Apr 17, 2024

DawoudSheraz Apr 17, 2024

DawoudSheraz Apr 17, 2024

DawoudSheraz Apr 17, 2024

DawoudSheraz Apr 29, 2024

DawoudSheraz Apr 30, 2024

DawoudSheraz Apr 30, 2024

DawoudSheraz Apr 30, 2024

arbrandes left a comment

DawoudSheraz May 10, 2024

DawoudSheraz commented May 21, 2024

hinakhadim commented May 21, 2024

DawoudSheraz commented May 27, 2024

		7. Repeat the same process for customizing the footer component if necessary.


		When there is a need to customize the ``@edx/frontend-component-header`` or ``@edx/frontend-component-footer`` component, it is necessary to address a crucial concerns to prevent dependency conflict errors during ``npm`` installation..

		1. Identify your openedx version, for example ``quince``.

		In this case, checkout custom branch from ``v4.11.1`` of header for Learning MFE and ``v5.0.0`` for Discussions MFE.

Docs: Add npm dependency conflict in troubleshooting section #200

Docs: Add npm dependency conflict in troubleshooting section #200

Conversation

hinakhadim commented Apr 2, 2024 • edited Loading

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

Choose a reason for hiding this 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

DawoudSheraz commented May 21, 2024

hinakhadim commented May 21, 2024

DawoudSheraz commented May 27, 2024

hinakhadim commented Apr 2, 2024 •

edited

Loading