docs: add an ADR for the footer links and styling

Author: Cup0fCoffee

docs/decisions/0002-footer-links.rst

@@ -0,0 +1,168 @@
+2. Footer Links
+########################
+.. The title should be a short noun phrase. For example, "1. Django IDA" or "9. LDAP for Multitenant Integration"; filename should be lowercase with punctuation removed and spaces replaced by dash
+
+Status
+******
+
+**Draft (=> Accepted)**
+
+.. **Accepted** *2023-05-11*
+
+.. Standard statuses
+    - **Draft** if the decision is newly proposed and in active discussion
+    - **Provisional** if the decision is still preliminary and in experimental phase
+    - **Accepted** *(date)* once it is agreed upon
+    - **Superseded** *(date)* with a reference to its replacement if a later ADR changes or reverses the decision
+
+    If an ADR has Draft status and the PR is under review, you can either use the intended final status (e.g. Provisional, Accepted, etc.), or you can clarify both the current and intended status using something like the following: "Draft (=> Provisional)". Either of these options is especially useful if the merged status is not intended to be Accepted.
+
+Context
+*******
+
+.. This section describes the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts.
+
+The footer component is basic - it only has a trademark logo and a language
+selector. It doesn't look similar to the legacy UI footer.
+
+It also doesn't have many customization options. You can customize
+LMS base URL and trade mark logo.
+
+If you want to have more advanced customizations, it's necessary to fork the
+component, modify it, and then install the fork as a package instead of the
+default footer at build time of MFEs.
+
+We want to make the MFE footer to closer resemble the legacy UI footer by
+adding the same footer links as in the legacy UI, and to make it easier to
+style the footer component.
+
+Decision
+********
+
+.. This section describes our response to these forces. It is stated in full sentences, with active voice. "We will …"
+
+Links
+=====
+
+For specifying the footer links, we are going to use `MFE's config mechanism`_.
+That would allow to specify a list of links in various ways:
+
+* At build time:
+  * Via environmental variables
+  * By providing them in ``env.config.js``, like so:
+
+    .. code-block:: javascript
+
+        const config = {
+            FOOTER_LINKS: [
+                {"url": "https://google.com", "text": "Terms of service"},
+                {"url": "https://duckduckgo.com", "text": "Acceptable Use Policy"},
+                {"url": "https://openedx.org", "text": "Privacy Policy"},
+            ],
+        };
+
+        export default config;
+
+* At runtime, via ``MFE_CONFIG`` in LMS's Django settings:
+
+    .. code-block:: python
+
+        MFE_CONFIG = {
+            "FOOTER_LINKS": [
+                {"url": "https://google.com", "text": "Terms of service"},
+                {"url": "https://duckduckgo.com", "text": "Acceptable Use Policy"},
+                {"url": "https://openedx.org", "text": "Privacy Policy"},
+            ],
+        }
+
+In case the array is undefined or empty, we won't render any links (or it's
+container).
+
+.. _MFE's config mechanism: https://github.com/openedx/frontend-platform/blob/master/src/config.js
+
+Styles
+======
+
+Since the root of the footer component is rendered as a footer HTML element, it
+is unique enough to use ``footer`` as selector. To make it more convenient to
+style footer's children, we will add unique class names, which will simplify
+the SCSS selectors.
+
+These SCSS styles can be put in a custom `branding package`_ into
+``paragon/_overrides.scss``.
+
+.. _branding package: https://github.com/openedx/brand-openedx
+
+Consequences
+************
+
+.. This section describes the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future.
+
+Positive
+========
+
+* There will be an option to make the MFE footer look similar to the legacy UI
+  footer, without having to create and maintain a fork.
+* Can add custom text/urls for links, unlike what branding v1 API allows.
+
+Negative
+========
+
+* There are already parameters that allow configuring the footer links for the
+  legacy UI, which means that configuration will be duplicated (potentially in
+  multiple places), in cases when the aim is to make the links in the legacy UI
+  and MFE footers that same.
+
+Rejected Alternatives
+*********************
+
+.. This section lists alternate options considered, described briefly, with pros and cons.
+
+React component props API
+=========================
+
+Instead of reading the configuration values in the component, we could be
+reading it somewhere else, and passing the values as props to the react
+component. We couldn't identify any pros to this approach, and the cons are the
+same as the cons from decoupling.
+
+Styling using CSS variables
+===========================
+
+Exposing styling customizations through the CSS variables would be similar to
+styling via CSS classes, and it would be better aligned with the current
+philosophy of Paragon, since it prefers CSS variables over custom CSS classes.
+
+The cons however, is that you can only expose one CSS attribute per variable.
+This means that we would either heavily limit the styling options, or would
+have to create many variables for each element and CSS attribute.
+
+Brading API V1
+==============
+
+LMS already has an API endpoint which could be used to retrieve the links that
+are used in the footer (legacy UI footer uses the same API) in JSON format -
+``api/branding/v1/footer``.
+
+The pros of using this approach would be that legacy and MFE footer would use
+the same API and would have the same links, without having to duplicate the
+configuration.
+
+The cons of using this approach are:
+
+* It would be necessary to make an additional API call from an MFE to get the
+  links.
+* No custom links, only what is allowed by the branding API.
+
+Third party footer
+==================
+
+The proposed changes won't affect anyone who won't use this feature. And these
+changes eliminate some frequent reasons for forking the footer component. Thus
+creating a third party footer for these features, instead of upstreaming them
+seems unjustified.
+
+.. References
+.. **********
+
+.. (Optional) List any additional references here that would be useful to the future reader. See `Documenting Architecture Decisions`_ for further input.