Story 2370: V3 Migration View Registry (boostorg#2308)

Author: julhoang

config/urls.py

@@ -1,7 +1,6 @@
 import logging
 
 from django.conf import settings
-from django.contrib.admin.views.decorators import staff_member_required
 from django.conf.urls.static import static
 from django.contrib import admin
 from django.urls import include, path, re_path, register_converter, reverse_lazy
@@ -20,6 +19,7 @@
     OKView,
 )
 from config.settings import DEBUG_TOOLBAR
+from config.v3_urls import v3_urlpatterns
 from core.views import (
     BSLView,
     BoostDevelopmentView,
@@ -30,8 +30,6 @@
     MarkdownTemplateView,
     TermsOfUseView,
     PrivacyPolicyView,
-    V3ComponentDemoView,
-    LearnPageView,
     ModernizedDocsView,
     RedirectToDocsView,
     RedirectToHTMLDocsView,
@@ -72,7 +70,6 @@
     NewsListView,
     PollCreateView,
     PollListView,
-    V3AllTypesCreateView,
     VideoCreateView,
     VideoListView,
 )
@@ -83,8 +80,6 @@
     CustomLoginView,
     CustomSignupView,
     CustomSocialSignupViewView,
-    V3LoginView,
-    V3SignupView,
     UserViewSet,
     UserAvatar,
     DeleteUserView,
@@ -251,26 +246,6 @@
             TemplateView.as_view(template_name="style_guide.html"),
             name="style-guide",
         ),
-        path(
-            "v3/demo/components/",
-            staff_member_required(V3ComponentDemoView.as_view()),
-            name="v3-demo-components",
-        ),
-        path(
-            "v3/demo/learn-page/",
-            staff_member_required(LearnPageView.as_view()),
-            name="v3-learn-page",
-        ),
-        path(
-            "v3/accounts/signup/",
-            V3SignupView.as_view(),
-            name="v3-signup",
-        ),
-        path(
-            "v3/accounts/login/",
-            V3LoginView.as_view(),
-            name="v3-login",
-        ),
         path("libraries/", LibraryListDispatcher.as_view(), name="libraries"),
         path(
             "libraries/<boostversionslug:version_slug>/<str:library_view_str>/",
@@ -329,7 +304,6 @@
         path("news/add/link/", LinkCreateView.as_view(), name="news-link-create"),
         path("news/add/poll/", PollCreateView.as_view(), name="news-poll-create"),
         path("news/add/video/", VideoCreateView.as_view(), name="news-video-create"),
-        path("v3/news/add/", V3AllTypesCreateView.as_view(), name="v3-news-create"),
         path("news/moderate/", EntryModerationListView.as_view(), name="news-moderate"),
         path(
             "news/moderate/<slug:slug>/",
@@ -448,6 +422,7 @@
         # Custom Django views (must come before Wagtail catch-all)
         path("testimonials/", include("testimonials.urls")),
     ]
+    + v3_urlpatterns
     + [
         re_path(
             r"^lib/(?P<library_slug>[^/]+)/?$",

config/v3_urls.py

@@ -0,0 +1,80 @@
+"""
+V3 URL Registry
+===============
+
+All URLs with the explicit `/v3/` prefix live here.
+
+All V3 views inherit from `V3Mixin` (see `core/mixins.py`). The test
+`core/tests/test_v3_registry.py` auto-discovers all `V3Mixin`
+subclasses via the URL resolver and verifies their templates exist — no
+manual registration needed.
+
+`V3Mixin` handles two cases based on class attributes:
+
+* **Both templates** (`template_name` + `v3_template_name`) — legacy
+  template by default, V3 template when the `v3` waffle flag is active.
+* **V3 template only** (`v3_template_name`, no `template_name`) —
+  returns 404 when the flag is off.
+
+Full-migration procedure
+------------------------
+The `v3` waffle flag and `V3Mixin` are migration scaffolding.
+
+A. Convert each view that has both templates
+     1. Set `template_name` to the V3 template path.
+     2. Fold `get_v3_context_data` into `get_context_data`.
+     3. Remove `V3Mixin` from the class bases.
+     4. Remove `v3_template_name` and `get_v3_context_data`.
+     5. Delete the legacy template.
+
+B. Promote each `/v3/` route
+   For each route in this file, move it into `config/urls.py` to
+   replace the legacy route (or create a permanent route if none
+   exists). Delete or rename the V3 view class as appropriate.
+
+C. Remove the flag from templates and JS
+   Unwrap every `{% flag "v3" %}` block and drop matching JS gates.
+
+D. Delete the scaffolding
+     1. `V3Mixin` from `core/mixins.py`.
+     2. `core/tests/test_v3_registry.py`.
+     3. The `v3` waffle flag record from the database.
+     4. This file and its import in `config/urls.py`.
+
+See `docs/django-waffle-v3-flag.md` for additional flag context.
+"""
+
+from django.contrib.admin.views.decorators import staff_member_required
+from django.urls import path
+
+from core.views import LearnPageView, V3ComponentDemoView
+from news.views import V3AllTypesCreateView
+from users.views import V3LoginView, V3SignupView
+
+v3_urlpatterns = [
+    path(
+        "v3/demo/components/",
+        staff_member_required(V3ComponentDemoView.as_view()),
+        name="v3-demo-components",
+    ),
+    path(
+        "v3/demo/learn-page/",
+        staff_member_required(LearnPageView.as_view()),
+        name="v3-learn-page",
+    ),
+    path(
+        "v3/news/add/",
+        V3AllTypesCreateView.as_view(),
+        name="v3-news-create",
+    ),
+    path(
+        "v3/accounts/signup/",
+        V3SignupView.as_view(),
+        name="v3-signup",
+    ),
+    path(
+        "v3/accounts/login/",
+        V3LoginView.as_view(),
+        name="v3-login",
+    ),
+]

core/mixins.py

@@ -1,3 +1,5 @@
+from django.http import Http404
+from django.urls import URLPattern, URLResolver, get_resolver
 from waffle import flag_is_active
 
 
@@ -11,6 +13,9 @@ class V3Mixin:
         v3_template_name: str — template to render when v3 is active
 
     And override get_v3_context_data() to supply view-specific context.
+
+    When the flag is off and no legacy template_name exists (i.e. a
+    V3-only view), dispatch returns 404.
     """
 
     v3_template_name = None
@@ -20,6 +25,8 @@ def dispatch(self, request, *args, **kwargs):
             self._v3_active = True
             return self.render_v3_response()
         self._v3_active = False
+        if not getattr(self, "template_name", None):
+            raise Http404
         return super().dispatch(request, *args, **kwargs)
 
     def get_v3_context_data(self, **kwargs):
@@ -35,3 +42,24 @@ def get_template_names(self):
         if getattr(self, "_v3_active", False):
             return [self.v3_template_name]
         return super().get_template_names()
+
+
+def iter_v3_views():
+    """Yield (URLPattern, view_class) for every V3Mixin view in the URL conf."""
+
+    def walk(patterns):
+        for entry in patterns:
+            if isinstance(entry, URLResolver):
+                yield from walk(entry.url_patterns)
+            elif isinstance(entry, URLPattern):
+                callback = entry.callback
+                view_class = None
+                while callback is not None:
+                    view_class = getattr(callback, "view_class", None)
+                    if view_class is not None:
+                        break
+                    callback = getattr(callback, "__wrapped__", None)
+                if view_class and issubclass(view_class, V3Mixin):
+                    yield entry, view_class
+
+    yield from walk(get_resolver().url_patterns)

core/tests/test_v3_registry.py

@@ -0,0 +1,48 @@
+"""Drift checks for V3 views.
+
+V3 views are discovered automatically by walking Django's URL resolver
+and finding every `V3Mixin` subclass — no manual list to maintain.
+
+Two tests run against the discovered set: one verifies at least one V3 view
+exists, and a parametrized one verifies template paths are valid.
+
+This whole module gets deleted when the migration ends — see
+`config/v3_urls.py` for teardown steps.
+"""
+
+from __future__ import annotations
+
+import pytest
+from django.template import TemplateDoesNotExist
+from django.template.loader import get_template
+
+from core.mixins import iter_v3_views
+
+
+def _get_v3_view_classes() -> set[type]:
+    return {view_class for _, view_class in iter_v3_views()}
+
+
+@pytest.fixture(scope="session")
+def v3_view_classes():
+    return sorted(_get_v3_view_classes(), key=lambda c: c.__name__)
+
+
+def test_v3_views_discovered(v3_view_classes):
+    """The resolver must find at least one V3 view."""
+    assert v3_view_classes, "No V3Mixin subclasses found in URL conf"
+
+
+@pytest.mark.parametrize(
+    "view_class",
+    _get_v3_view_classes(),
+    ids=lambda c: c.__name__,
+)
+def test_v3_template_exists(view_class):
+    """Every V3 view must point to a `v3_template_name` that Django can load."""
+    template = getattr(view_class, "v3_template_name", None)
+    assert template, f"{view_class.__name__}: no v3_template_name set"
+    try:
+        get_template(template)
+    except TemplateDoesNotExist:
+        pytest.fail(f"{view_class.__name__}: template {template!r} not found")

core/views.py

@@ -6,7 +6,6 @@
 
 from textwrap import dedent
 from urllib.parse import urljoin
-from waffle import flag_is_active
 
 import structlog
 from bs4 import BeautifulSoup
@@ -43,7 +42,7 @@
 )
 from versions.models import Version, docs_path_to_boost_name
 
-from .mixins import V3Mixin
+from .mixins import V3Mixin, iter_v3_views
 from .asciidoc import convert_adoc_to_html
 from .boostrenderer import (
     convert_img_paths,
@@ -280,11 +279,6 @@ def get_v3_context_data(self, **kwargs):
 class LearnPageView(V3Mixin, TemplateView):
     v3_template_name = "v3/learn_page.html"
 
-    def dispatch(self, request, *args, **kwargs):
-        if not flag_is_active(request, "v3"):
-            return HttpResponseNotFound()
-        return super().dispatch(request, *args, **kwargs)
-
     def get_v3_context_data(self, **kwargs):
         ctx = self.get_context_data(**kwargs)
         ctx["learn_card_data"] = [
@@ -1247,10 +1241,10 @@ def get(self, request: HttpRequest, campaign_identifier: str, main_path: str = "
         return HttpResponseRedirect(redirect_path)
 
 
-class V3ComponentDemoView(TemplateView):
+class V3ComponentDemoView(V3Mixin, TemplateView):
     """Demo page for V3 design system components."""
 
-    template_name = "base.html"
+    v3_template_name = "base.html"
 
     def get_context_data(self, **kwargs):
         from django.urls import reverse
@@ -1913,4 +1907,18 @@ def get_context_data(self, **kwargs):
             )
         context["demo_library_items"] = demo_library_items
 
+        # V3 paths registry
+        v3_paths = [
+            {
+                "class_name": view_class.__name__,
+                "url": f"/{entry.pattern}",
+                "url_name": entry.name or "",
+                "v3_template": getattr(view_class, "v3_template_name", ""),
+                "has_legacy_template": bool(getattr(view_class, "template_name", None)),
+            }
+            for entry, view_class in iter_v3_views()
+        ]
+        v3_paths.sort(key=lambda p: p["class_name"])
+        context["v3_paths"] = v3_paths
+
         return context

news/views.py

@@ -27,6 +27,7 @@
 from django.views.generic.detail import SingleObjectMixin
 from itsdangerous import URLSafeTimedSerializer, SignatureExpired, BadData
 
+from core.mixins import V3Mixin
 from .acl import can_approve
 from .constants import NEWS_APPROVAL_SALT, MAGIC_LINK_EXPIRATION
 from .forms import BlogPostForm, EntryForm, LinkForm, NewsForm, PollForm, VideoForm
@@ -341,8 +342,8 @@ def get_context_data(self, **kwargs):
         return context
 
 
-class V3AllTypesCreateView(AllTypesCreateView):
-    template_name = "news/v3/create.html"
+class V3AllTypesCreateView(V3Mixin, AllTypesCreateView):
+    v3_template_name = "news/v3/create.html"
     http_method_names = ["get", "post"]
 
     _POST_TYPE_MAP = {
@@ -352,6 +353,13 @@ class V3AllTypesCreateView(AllTypesCreateView):
         "video": (Video, VideoForm),
     }
 
+    def dispatch(self, request, *args, **kwargs):
+        # Run AllTypesCreateView's profile-completeness guard before V3Mixin takes over.
+        response = AllTypesCreateView.dispatch(self, request, *args, **kwargs)
+        if response.status_code != 200:
+            return response
+        return super().dispatch(request, *args, **kwargs)
+
     def get_context_data(self, **kwargs):
         context = super().get_context_data(**kwargs)
         context.update(_v3_create_context())