Add Policies FAQ to links and restructure links to make them more obvious (#23689)

* Refactor documentation URLs in `docs` view and update agreement message in template

- Replaced hardcoded URLs in the `docs` view with helper functions for better maintainability.
- Updated the agreement message in the `agreement.html` template to include a link to the FAQ and improved wording.
- Adjusted test case to reflect the change in the URL structure for the policies documentation.

Refactor URL generation in `docs` view and enhance test assertions

- Introduced a helper function `get_url` to streamline URL construction in the `docs` view.
- Updated test cases to assert the presence of the `utm_referrer=amo` query parameter for 301 redirects.
- Improved readability of the test case by unpacking the URL and status code directly in the loop.

Update src/olympia/devhub/templates/devhub/includes/agreement.html

Co-authored-by: Copilot <[email protected]>

TMP: better name for argument

* TMP: fix broken link rendering false positives by adding actually referenced links to the docs link test

* TMP: fix broken test

Author: KevinMind

src/olympia/devhub/templates/devhub/includes/agreement.html

@@ -1,11 +1,13 @@
 <form method="post">
   {% if not agreement_form.has_error('__all__') %}
   <p>
-    {{ agreement_message }}
+    {% trans faq_url=url('devhub.docs', 'policies/faq'), a_attrs='target="_blank" rel="noopener noreferrer"' %}
+    Before starting, please read and accept our Firefox Add-on Distribution Agreement, Review Policies and Rules and our <a {{ a_attrs }} href="{{ faq_url }}">Frequently Asked Questions</a>. The Firefox Add-on Distribution Agreement also links to our Privacy Notice which explains how we handle your information.
+    {% endtrans %}
   </p>
   <ul class="agreement-links">
     <li>{{ agreement_form.distribution_agreement }}<a href="{{ url('devhub.docs', 'policies/agreement') }}" target="_blank" rel="noopener noreferrer">{{ _('Firefox Add-on Distribution Agreement') }}</a> {{ agreement_form.distribution_agreement.errors }}</li>
-    <li>{{ agreement_form.review_policy }}<a href="{{ url('devhub.docs', 'policies/reviews') }}" target="_blank" rel="noopener noreferrer">{{ _('Review Policies and Rules') }}</a> {{ agreement_form.review_policy.errors }}</li>
+    <li>{{ agreement_form.review_policy }}<a href="{{ url('devhub.docs', 'policies') }}" target="_blank" rel="noopener noreferrer">{{ _('Review Policies and Rules') }}</a> {{ agreement_form.review_policy.errors }}</li>
   </ul>
   <p>
     {{ _('I have read and accept this Agreement and the Rules and Policies') }}.

src/olympia/devhub/tests/test_views.py

@@ -2054,22 +2054,39 @@ def test_doc_urls(self):
         assert '/en-US/developers/docs/te' == reverse('devhub.docs', args=['te'])
         assert '/en-US/developers/docs/te/st', reverse('devhub.docs', args=['te/st'])
 
+        self.client.force_login(user_factory(read_dev_agreement=None))
+        response = self.client.get(reverse('devhub.submit.agreement'))
+        doc = pq(response.content)
+
+        # Extract the last part of the docs URL path as the "name" for each link.
+        links = [
+            a.attr['href'].rstrip('/').split('/developers/docs/', 1)[-1] or ''
+            for a in doc('a').items()
+            if '/developers/docs/' in a.attr['href']
+        ]
+
+        assert len(links) == 3
+
         urls = [
-            (reverse('devhub.docs', args=['getting-started']), 301),
-            (reverse('devhub.docs', args=['how-to']), 301),
-            (reverse('devhub.docs', args=['how-to/other-addons']), 301),
-            (reverse('devhub.docs', args=['fake-page']), 404),
-            (reverse('devhub.docs', args=['how-to/fake-page']), 404),
+            # None link
             (reverse('devhub.docs'), 301),
+            # Valid links
+            *[(reverse('devhub.docs', args=[link]), 301) for link in links],
+            # Invalid links
+            (reverse('devhub.docs', args=['fake-page']), 404),
+            *[(reverse('devhub.docs', args=[f'fake-{link}']), 404) for link in links],
         ]
 
         index = reverse('devhub.index')
 
-        for url in urls:
-            response = self.client.get(url[0])
-            assert response.status_code == url[1]
+        for [url, status_code] in urls:
+            response = self.client.get(url)
+            assert response.status_code == status_code
+
+            if status_code == 301:
+                assert 'utm_referrer=amo' in response.url
 
-            if url[1] == 302:  # Redirect to the index page
+            if status_code == 302:  # Redirect to the index page
                 self.assert3xx(response, index)
 
 

src/olympia/devhub/views.py

@@ -2,7 +2,7 @@
 import os
 import time
 from copy import deepcopy
-from urllib.parse import quote
+from urllib.parse import quote, urlencode, urljoin
 from uuid import UUID, uuid4
 
 from django import forms as django_forms, http
@@ -72,7 +72,6 @@
 from olympia.reviewers.models import Whiteboard
 from olympia.reviewers.utils import ReviewHelper
 from olympia.users.models import (
-    DeveloperAgreementRestriction,
     SuppressedEmailVerification,
 )
 from olympia.users.tasks import send_suppressed_email_confirmation
@@ -1952,26 +1951,38 @@ def request_review(request, addon_id, addon):
 
 
 def docs(request, doc_name=None):
+    def get_url(base, doc_path=None):
+        base_url = urljoin(base, doc_path)
+        query = urlencode({'utm_referrer': 'amo'})
+        return f'{base_url}?{query}'
+
+    def mdn_url(doc_path):
+        return get_url(MDN_BASE, doc_path)
+
+    def ext_url(doc_path):
+        return get_url(settings.EXTENSION_WORKSHOP_URL, doc_path)
+
     mdn_docs = {
-        None: '',
-        'getting-started': '',
-        'reference': '',
-        'how-to': '',
-        'how-to/getting-started': '',
-        'how-to/extension-development': '#Extensions',
-        'how-to/other-addons': '#Other_types_of_add-ons',
-        'how-to/thunderbird-mobile': '#Application-specific',
-        'how-to/theme-development': '#Themes',
-        'themes': '/Themes/Background',
-        'themes/faq': '/Themes/Background/FAQ',
-        'policies': '/AMO/Policy',
-        'policies/reviews': '/AMO/Policy/Reviews',
-        'policies/contact': '/AMO/Policy/Contact',
-        'policies/agreement': '/AMO/Policy/Agreement',
+        None: mdn_url(''),
+        'getting-started': mdn_url(''),
+        'reference': mdn_url(''),
+        'how-to': mdn_url(''),
+        'how-to/getting-started': mdn_url(''),
+        'how-to/extension-development': mdn_url('#Extensions'),
+        'how-to/other-addons': mdn_url('#Other_types_of_add-ons'),
+        'how-to/thunderbird-mobile': mdn_url('#Application-specific'),
+        'how-to/theme-development': mdn_url('#Themes'),
+        'themes': mdn_url('/Themes/Background'),
+        'themes/faq': mdn_url('/Themes/Background/FAQ'),
+        'policies': ext_url('/documentation/publish/add-on-policies'),
+        'policies/faq': ext_url('/documentation/publish/add-on-policies-faq'),
+        'policies/agreement': ext_url(
+            '/documentation/publish/firefox-add-on-distribution-agreement'
+        ),
     }
 
     if doc_name in mdn_docs:
-        return redirect(MDN_BASE + mdn_docs[doc_name], permanent=True)
+        return redirect(mdn_docs[doc_name], permanent=True)
 
     raise http.Http404()
 
@@ -2009,7 +2020,6 @@ def render_agreement(request, template, next_step, **extra_context):
         # potential errors highlighted)
         context = {
             'agreement_form': form,
-            'agreement_message': str(DeveloperAgreementRestriction.error_message),
         }
         context.update(extra_context)
         return TemplateResponse(request, template, context=context)