docs: Add npm dependency conflict in troubleshooting section (#200)

README.rst

@@ -42,79 +42,79 @@ To check what the current value of `MFE_HOST` is actually set to, run::
 Authn
 ~~~~~
 
-.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/screenshots/authn.png
+.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/media/authn.png
     :alt: Authn MFE screenshot
 
 This is a micro-frontend application responsible for the login, registration and password reset functionality.
 
 Account
 ~~~~~~~
 
-.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/screenshots/account.png
+.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/media/account.png
     :alt: Account MFE screenshot
 
 An MFE to manage account-specific information for every LMS user. Each user's account page is available at ``http(s)://{{ MFE_HOST }}/account``. For instance, when running locally: https://apps.local.edly.io/account.
 
 Communications
 ~~~~~~~~~~~~~~
 
-.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/screenshots/communications.png
+.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/media/communications.png
     :alt: Communications MFE screenshot
 
 The Communications micro-frontend exposes an interface for course teams to communicate with learners.  It achieves this by allowing instructors to send out emails in bulk, either by scheduling them or on demand.
 
 Course Authoring
 ~~~~~~~~~~~~~~~~
 
-.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/screenshots/course-authoring.png
+.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/media/course-authoring.png
     :alt: Course Authoring MFE screenshot
 
 This MFE is meant for course authors and maintainers. For a given course, it exposes a "Pages & Resources" menu in Studio where one can enable or disable a variety of features, including, for example, the Wiki and Discussions.  Optionally, it allows authors to replace the legacy HTML, Video, and Problem authoring tools with experimental React-based versions, as well as exposing a new proctoring interface that can be enabled if the `edx-exams <https://github.com/edx/edx-exams>`_ service is available.
 
 Discussions
 ~~~~~~~~~~~
 
-.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/screenshots/discussions.png
+.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/media/discussions.png
     :alt: Discussions MFE screenshot
 
 The Discussions MFE updates the previous discussions UI with a new look and better features.
 
 Gradebook
 ~~~~~~~~~
 
-.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/screenshots/gradebook.png
+.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/media/gradebook.png
     :alt: Gradebook MFE screenshot
 
 This instructor-only MFE is for viewing individual and aggregated grade results for a course. To access this MFE, go to a course → Instructor tab → Student Admin → View gradebook. The URL should be: ``http(s)://{{ MFE_HOST }}/gradebook/{{ course ID }}``. When running locally, the gradebook of the demo course is available at: http://apps.local.edly.io/gradebook/course-v1:edX+DemoX+Demo_Course
 
 Learner Dashboard
 ~~~~~~~~~~~~~~~~~
 
-.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/screenshots/learner-dashboard.png
+.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/media/learner-dashboard.png
     :alt: Learner Dashboard MFE screenshot
 
 The Learner Dashboard MFE provides a clean and functional interface to allow learners to view all of their open enrollments, as well as take relevant actions on those enrollments.
 
 Learning
 ~~~~~~~~
 
-.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/screenshots/learning.png
+.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/media/learning.png
     :alt: Learning MFE screenshot
 
 The Learning MFE replaces the former courseware, which is the core part of the LMS where students follow courses.
 
 ORA Grading
 ~~~~~~~~~~~
 
-.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/screenshots/ora-grading.png
+.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/media/ora-grading.png
     :alt: ORA Grading MFE screenshot
 
 When enabled, Open Response Assessments ("ORA") that have a staff grading step will link to this new MFE, either when clicking "Grade Available Responses" from the exercise itself, or via a link in the Instructor Dashboard.  It is meant to streamline the grading process with better previews of submitted content.
 
 Profile
 ~~~~~~~
 
-.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/screenshots/profile.png
+.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/media/profile.png
     :alt: Profile MFE screenshot
 
 Edit and display user-specific profile information. The profile page of every user is visible at ``http(s)://{{ MFE_HOST }}/profile/u/{{ username }}``. For instance, when running locally, the profile page of the "admin" user is: http://apps.local.edly.io/profile/u/admin.
@@ -525,7 +525,44 @@ File changed: ``tutormfe/templates/mfe/apps/mfe/Caddyfile``
 Troubleshooting
 ---------------
 
-This Tutor plugin is maintained by Adolfo Brandes from `Axim <https://openedx.org>`__. Community support is available from the official `Open edX forum <https://discuss.openedx.org>`__. Do you need help with this plugin? See the `troubleshooting <https://docs.tutor.edly.io/troubleshooting.html>`__ section from the Tutor documentation.
+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, 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:
+
+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``. Learning and Learner Dashboard MFEs are mentioned only as an example. Hence, This step can be applied to all MFEs.
+3. Determine the versions of ``@edx/frontend-platform`` used in MFEs. Also, check that the header/footer you plan to customize is compatible with the same version of ``@edx/frontend-platform`` specified in their ``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/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 or vice versa.
+
+.. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/media/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 Discussions 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. 
+In this case, checkout custom branch from ``v4.11.1`` of header for Learning MFE and ``v5.0.0`` for Discussions MFE. You can install your customized header versions in their respective MFEs as shown below::
+
+    hooks.Filters.ENV_PATCHES.add_items(
+        [
+            (
+                "mfe-dockerfile-post-npm-install-learning",
+                """
+        RUN npm install '@edx/frontend-component-header@npm:@custom/frontend-component-header@^4.11.1'
+        """
+            ),
+            (
+                "mfe-dockerfile-post-npm-install-discussions",
+                """
+        RUN npm install '@edx/frontend-component-header@npm:@custom/frontend-component-header@^5.0.0'
+        """
+            ),
+        ]
+    )
+
+
+This Tutor plugin is maintained by Adolfo Brandes from `tCRIL <https://openedx.org>`__. Community support is available from the official `Open edX forum <https://discuss.openedx.org>`__. Do you need help with this plugin? See the `troubleshooting <https://docs.tutor.edly.io/troubleshooting.html>`__ section from the Tutor documentation.
 
 License
 -------