From 9b8ef3953d6ea3bb6e4cee820960ee56feb0eb87 Mon Sep 17 00:00:00 2001
From: owenatgov <owen.jones@digital.cabinet-office.gov.uk>
Date: Mon, 12 Sep 2022 16:06:47 +0100
Subject: [PATCH 1/6] Deprecate govuk-compatibility mixin

To suppress lots of warnings when team members run this code locally due to parts of our own code currently using compatibility mode, we temporarily split `govuk-compatibility` into a public and private mixin. The private mixin is just `_govuk-compaitbility` as is and the public mixin references the private mixin but adds a warning. This is specifically to catch when users are using `govuk-compatibility` in their own code.
---
 src/govuk/components/button/_index.scss |  6 ++---
 src/govuk/components/footer/_index.scss |  2 +-
 src/govuk/components/table/_index.scss  |  2 +-
 src/govuk/core/_section-break.scss      |  2 +-
 src/govuk/helpers/_links.scss           | 12 ++++-----
 src/govuk/tools/_compatibility.scss     | 26 ++++++++++++++-----
 src/govuk/tools/compatibility.test.js   | 34 ++++++++++++++++++++++++-
 7 files changed, 65 insertions(+), 19 deletions(-)

diff --git a/src/govuk/components/button/_index.scss b/src/govuk/components/button/_index.scss
index a0f4e53fdf..e616038e93 100644
--- a/src/govuk/components/button/_index.scss
+++ b/src/govuk/components/button/_index.scss
@@ -119,7 +119,7 @@ $govuk-button-text-colour: govuk-colour("white") !default;
     // we need to override the text colour for that combination of selectors so
     // so that unvisited links styled as buttons do not end up with dark blue
     // text when focussed.
-    @include govuk-compatibility(govuk_template) {
+    @include _govuk-compatibility(govuk_template) {
       &:link:focus {
         color: $govuk-button-text-colour;
       }
@@ -202,7 +202,7 @@ $govuk-button-text-colour: govuk-colour("white") !default;
     // we need to override the text colour for that combination of selectors so
     // so that unvisited links styled as buttons do not end up with dark blue
     // text when focussed.
-    @include govuk-compatibility(govuk_template) {
+    @include _govuk-compatibility(govuk_template) {
       &:link:focus {
         color: $govuk-secondary-button-text-colour;
       }
@@ -234,7 +234,7 @@ $govuk-button-text-colour: govuk-colour("white") !default;
     // we need to override the text colour for that combination of selectors so
     // so that unvisited links styled as buttons do not end up with dark blue
     // text when focussed.
-    @include govuk-compatibility(govuk_template) {
+    @include _govuk-compatibility(govuk_template) {
       &:link:focus {
         color: $govuk-warning-button-text-colour;
       }
diff --git a/src/govuk/components/footer/_index.scss b/src/govuk/components/footer/_index.scss
index 9c4655912b..4c24b2c0ff 100644
--- a/src/govuk/components/footer/_index.scss
+++ b/src/govuk/components/footer/_index.scss
@@ -52,7 +52,7 @@
     // alphagov/govuk_template includes a specific a:link:focus selector
     // designed to make unvisited links a slightly darker blue when focussed, so
     // we need to override the text colour for that combination of selectors.
-    @include govuk-compatibility(govuk_template) {
+    @include _govuk-compatibility(govuk_template) {
       &:link:focus {
         @include govuk-text-colour;
       }
diff --git a/src/govuk/components/table/_index.scss b/src/govuk/components/table/_index.scss
index c7c0a200d7..c52eaa32f1 100644
--- a/src/govuk/components/table/_index.scss
+++ b/src/govuk/components/table/_index.scss
@@ -21,7 +21,7 @@
     vertical-align: top;
     // GOV.UK Elements sets the font-size and line-height for all headers and cells
     // in tables.
-    @include govuk-compatibility(govuk_elements) {
+    @include _govuk-compatibility(govuk_elements) {
       font-size: inherit;
       line-height: inherit;
     }
diff --git a/src/govuk/core/_section-break.scss b/src/govuk/core/_section-break.scss
index a316d31bf7..dea97fbd6d 100644
--- a/src/govuk/core/_section-break.scss
+++ b/src/govuk/core/_section-break.scss
@@ -6,7 +6,7 @@
 
     // fix double-width section break and forced visible section break
     // when combined with styles from alphagov/elements
-    @include govuk-compatibility(govuk_elements) {
+    @include _govuk-compatibility(govuk_elements) {
       height: 0;
     }
   }
diff --git a/src/govuk/helpers/_links.scss b/src/govuk/helpers/_links.scss
index 12071d15e0..f48dc42175 100644
--- a/src/govuk/helpers/_links.scss
+++ b/src/govuk/helpers/_links.scss
@@ -102,7 +102,7 @@
   // we need to override the text colour for that combination of selectors so
   // so that unvisited links styled as buttons do not end up with dark blue
   // text when focussed.
-  @include govuk-compatibility(govuk_template) {
+  @include _govuk-compatibility(govuk_template) {
     &:link:focus {
       color: $govuk-focus-text-colour;
     }
@@ -150,7 +150,7 @@
   // we need to override the text colour for that combination of selectors so
   // so that unvisited links styled as buttons do not end up with dark blue
   // text when focussed.
-  @include govuk-compatibility(govuk_template) {
+  @include _govuk-compatibility(govuk_template) {
     &:link:focus {
       color: $govuk-focus-text-colour;
     }
@@ -198,7 +198,7 @@
   // we need to override the text colour for that combination of selectors so
   // so that unvisited links styled as buttons do not end up with dark blue
   // text when focussed.
-  @include govuk-compatibility(govuk_template) {
+  @include _govuk-compatibility(govuk_template) {
     &:link:focus {
       color: $govuk-focus-text-colour;
     }
@@ -241,7 +241,7 @@
   // alphagov/govuk_template includes a specific a:link:focus selector designed
   // to make unvisited links a slightly darker blue when focussed, so we need to
   // override the text colour for that combination of selectors.
-  @include govuk-compatibility(govuk_template) {
+  @include _govuk-compatibility(govuk_template) {
     &:link:focus {
       @include govuk-text-colour;
     }
@@ -286,7 +286,7 @@
   // alphagov/govuk_template includes a specific a:link:focus selector designed
   // to make unvisited links a slightly darker blue when focussed, so we need to
   // override the text colour for that combination of selectors.
-  @include govuk-compatibility(govuk_template) {
+  @include _govuk-compatibility(govuk_template) {
     &:link:focus {
       @include govuk-text-colour;
     }
@@ -329,7 +329,7 @@
   // alphagov/govuk_template includes a specific a:link:focus selector designed
   // to make unvisited links a slightly darker blue when focussed, so we need to
   // override the text colour for that combination of selectors.
-  @include govuk-compatibility(govuk_template) {
+  @include _govuk-compatibility(govuk_template) {
     &:link:focus {
       color: $govuk-focus-text-colour;
     }
diff --git a/src/govuk/tools/_compatibility.scss b/src/govuk/tools/_compatibility.scss
index 9decd65355..54004a04b3 100644
--- a/src/govuk/tools/_compatibility.scss
+++ b/src/govuk/tools/_compatibility.scss
@@ -2,6 +2,20 @@
 /// @group tools/compatibility-mode
 ////
 
+/// Temporary private version of govuk-compatibility to avoid deprecation warnings
+///
+/// @access private
+
+@mixin _govuk-compatibility($product) {
+  @if map-has-key($_govuk-compatibility, $product) {
+    @if map-get($_govuk-compatibility, $product) == true {
+      @content;
+    }
+  } @else {
+    @error "Non existent product '#{$product}'";
+  }
+}
+
 /// Conditional Compatibility Mixin
 ///
 /// Selectively output a block (available to the mixin as @content) if a given
@@ -24,13 +38,13 @@
 ///   this product
 /// @throw Errors if product name is not recognised
 /// @access public
+/// @deprecated Will be removed in v5.0 with the rest of the compatibility mode
+/// suite of tools and settings
 
 @mixin govuk-compatibility($product) {
-  @if map-has-key($_govuk-compatibility, $product) {
-    @if map-get($_govuk-compatibility, $product) == true {
-      @content;
-    }
-  } @else {
-    @error "Non existent product '#{$product}'";
+  @warn "govuk-compatibility is deprecated. " +
+    "From version 5.0, GOV.UK Frontend will not support compatibility mode";
+  @include _govuk-compatibility($product) {
+    @content;
   }
 }
diff --git a/src/govuk/tools/compatibility.test.js b/src/govuk/tools/compatibility.test.js
index e195c5c2af..941b821e1c 100644
--- a/src/govuk/tools/compatibility.test.js
+++ b/src/govuk/tools/compatibility.test.js
@@ -1,7 +1,16 @@
+const sass = require('node-sass')
 const { renderSass } = require('../../../lib/jest-helpers')
 
+// Create a mock warn function that we can use to override the native @warn
+// function, that we can make assertions about post-render.
+const mockWarnFunction = jest.fn()
+  .mockReturnValue(sass.NULL)
+
 const sassConfig = {
-  outputStyle: 'compressed'
+  outputStyle: 'compressed',
+  functions: {
+    '@warn': mockWarnFunction
+  }
 }
 
 describe('@mixin govuk-compatibility', () => {
@@ -55,4 +64,27 @@ describe('@mixin govuk-compatibility', () => {
       .rejects
       .toThrow('Non existent product \'non_existent_app\'')
   })
+
+  it('outputs a deprecation warning when called', async () => {
+    const sass = `
+      $_govuk-compatibility: (existing_app: true);
+
+      @import "tools/compatibility";
+
+      @include govuk-compatibility(existing_app) {
+        .foo {
+          color: red;
+        }
+      }`
+
+    await renderSass({ data: sass, ...sassConfig }).then(() => {
+      // Expect our mocked @warn function to have been called once with a single
+      // argument, which should be the deprecation notice
+      return expect(mockWarnFunction.mock.calls[0][0].getValue())
+        .toEqual(
+          'govuk-compatibility is deprecated. From version 5.0, GOV.UK Frontend ' +
+          'will not support compatibility mode'
+        )
+    })
+  })
 })

From 9884210a0f4b3bcb4f0ed4fad855e3a3f7a2f684 Mon Sep 17 00:00:00 2001
From: owenatgov <owen.jones@digital.cabinet-office.gov.uk>
Date: Mon, 12 Sep 2022 16:41:32 +0100
Subject: [PATCH 2/6] Deprecate $govuk-use-legacy-palette

---
 src/govuk/helpers/colour.test.js         | 25 +++++++++++++++++++++++-
 src/govuk/settings/_colours-palette.scss | 12 ++++++++++++
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/src/govuk/helpers/colour.test.js b/src/govuk/helpers/colour.test.js
index 06abee6113..da9a187423 100644
--- a/src/govuk/helpers/colour.test.js
+++ b/src/govuk/helpers/colour.test.js
@@ -1,7 +1,16 @@
+const sass = require('node-sass')
 const { renderSass } = require('../../../lib/jest-helpers')
 
+// Create a mock warn function that we can use to override the native @warn
+// function, that we can make assertions about post-render.
+const mockWarnFunction = jest.fn()
+  .mockReturnValue(sass.NULL)
+
 const sassConfig = {
-  outputStyle: 'compact'
+  outputStyle: 'compact',
+  functions: {
+    '@warn': mockWarnFunction
+  }
 }
 
 describe('@function govuk-colour', () => {
@@ -120,6 +129,20 @@ describe('@function govuk-colour', () => {
           'Unknown colour `hooloovoo`'
         )
     })
+
+    it('outputs a deprecation warning when set to true', async () => {
+      const sass = `${sassBootstrap}`
+
+      await renderSass({ data: sass, ...sassConfig }).then(() => {
+        // Expect our mocked @warn function to have been called once with a single
+        // argument, which should be the deprecation notice
+        return expect(mockWarnFunction.mock.calls[0][0].getValue())
+          .toEqual(
+            '$govuk-use-legacy-palette is deprecated. ' +
+            'Only the modern colour palette will be supported from v5.0'
+          )
+      })
+    })
   })
 
   describe('when $govuk-use-legacy-palette is false', () => {
diff --git a/src/govuk/settings/_colours-palette.scss b/src/govuk/settings/_colours-palette.scss
index d81d98d62f..233166deff 100644
--- a/src/govuk/settings/_colours-palette.scss
+++ b/src/govuk/settings/_colours-palette.scss
@@ -15,6 +15,8 @@
 ///
 /// @type Boolean
 /// @access public
+/// @deprecated Will be removed in v5.0 with the rest of the compatibility mode
+/// suite of tools and settings
 
 $govuk-use-legacy-palette: if(
   (
@@ -26,6 +28,16 @@ $govuk-use-legacy-palette: if(
   false
 ) !default;
 
+// Only show the deprecation warning if user is setting $govuk-use-legacy-palette
+// manually instead of automatically via compatibility variables
+@if $govuk-use-legacy-palette == true and
+  $govuk-compatibility-govukfrontendtoolkit == false and
+  $govuk-compatibility-govuktemplate == false and
+  $govuk-compatibility-govukelements == false {
+  @warn "$govuk-use-legacy-palette is deprecated. " +
+    "Only the modern colour palette will be supported from v5.0";
+}
+
 /// Modern colour palette
 ///
 /// This exists only because you cannot easily set a !default variable

From 6512c192a957fe38bf4148336f8848d574f4308f Mon Sep 17 00:00:00 2001
From: owenatgov <owen.jones@digital.cabinet-office.gov.uk>
Date: Mon, 12 Sep 2022 16:53:01 +0100
Subject: [PATCH 3/6] Deprecate $govuk-use-legacy-font

---
 src/govuk/settings/_typography-font.scss | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/src/govuk/settings/_typography-font.scss b/src/govuk/settings/_typography-font.scss
index a6fbcf76b2..5e9028ce3a 100644
--- a/src/govuk/settings/_typography-font.scss
+++ b/src/govuk/settings/_typography-font.scss
@@ -13,6 +13,8 @@
 ///
 /// @type Boolean
 /// @access public
+/// @deprecated Will be removed in v5.0 with the rest of the compatibility mode
+/// suite of tools and settings
 
 $govuk-use-legacy-font: if(
   (
@@ -24,6 +26,17 @@ $govuk-use-legacy-font: if(
   false
 ) !default;
 
+// Only show the deprecation warning if user is setting $govuk-use-legacy-font
+// manually instead of automatically via compatibility variables
+@if $govuk-use-legacy-font == true and
+  $govuk-compatibility-govukfrontendtoolkit == false and
+  $govuk-compatibility-govuktemplate == false and
+  $govuk-compatibility-govukelements == false {
+  @warn "$govuk-use-legacy-font is deprecated. " +
+    "From version 5.0, GOV.UK Frontend will only support the included version " +
+    "of GDS Transport";
+}
+
 // =========================================================
 // Font families
 // =========================================================

From 56d6985303ace3c148fdec0ced191a49844d3620 Mon Sep 17 00:00:00 2001
From: owenatgov <owen.jones@digital.cabinet-office.gov.uk>
Date: Mon, 12 Sep 2022 16:58:18 +0100
Subject: [PATCH 4/6] Deprecate $govuk-typography-use-rem

---
 src/govuk/helpers/typography.test.js          | 29 +++++++++++++++++--
 .../settings/_typography-responsive.scss      | 12 ++++++++
 2 files changed, 39 insertions(+), 2 deletions(-)

diff --git a/src/govuk/helpers/typography.test.js b/src/govuk/helpers/typography.test.js
index a45e15d7a2..f636b66dfc 100644
--- a/src/govuk/helpers/typography.test.js
+++ b/src/govuk/helpers/typography.test.js
@@ -1,9 +1,18 @@
-const outdent = require('outdent')
 
+const sass = require('node-sass')
+const outdent = require('outdent')
 const { renderSass } = require('../../../lib/jest-helpers')
 
+// Create a mock warn function that we can use to override the native @warn
+// function, that we can make assertions about post-render.
+const mockWarnFunction = jest.fn()
+  .mockReturnValue(sass.NULL)
+
 const sassConfig = {
-  outputStyle: 'nested'
+  outputStyle: 'nested',
+  functions: {
+    '@warn': mockWarnFunction
+  }
 }
 
 const sassBootstrap = `
@@ -391,6 +400,22 @@ describe('@mixin govuk-typography-responsive', () => {
                 line-height: 1.42857 !important; } }`)
       })
     })
+
+    it('outputs a deprecation warning when set to false', async () => {
+      const sass = `
+        $govuk-typography-use-rem: false;
+        ${sassBootstrap}`
+
+      await renderSass({ data: sass, ...sassConfig }).then(() => {
+        // Expect our mocked @warn function to have been called once with a single
+        // argument, which should be the deprecation notice
+        return expect(mockWarnFunction.mock.calls[0][0].getValue())
+          .toEqual(
+            '$govuk-typography-use-rem is deprecated. ' +
+            'From version 5.0, GOV.UK Frontend will not support disabling rem font sizes'
+          )
+      })
+    })
   })
 
   describe('when compatibility mode is set', () => {
diff --git a/src/govuk/settings/_typography-responsive.scss b/src/govuk/settings/_typography-responsive.scss
index 21203c3bac..ef5298a96a 100644
--- a/src/govuk/settings/_typography-responsive.scss
+++ b/src/govuk/settings/_typography-responsive.scss
@@ -13,6 +13,8 @@
 ///
 /// @type Boolean
 /// @access public
+/// @deprecated Will be removed in v5.0 with the rest of the compatibility mode
+/// suite of tools and settings
 
 $govuk-typography-use-rem: if(
   (
@@ -24,6 +26,16 @@ $govuk-typography-use-rem: if(
   true
 ) !default;
 
+// Only show the deprecation warning if user is setting $govuk-typography-use-rem
+// manually instead of automatically via compatibility variables
+@if $govuk-typography-use-rem == false and
+  $govuk-compatibility-govukfrontendtoolkit == false and
+  $govuk-compatibility-govuktemplate == false and
+  $govuk-compatibility-govukelements == false {
+  @warn "$govuk-typography-use-rem is deprecated. " +
+    "From version 5.0, GOV.UK Frontend will not support disabling rem font sizes";
+}
+
 /// Root font size
 ///
 /// This is used to calculate rem sizes for the typography, and should match the

From 3d37598317d9d899e9dbe3931a54fede623a276a Mon Sep 17 00:00:00 2001
From: owenatgov <owen.jones@digital.cabinet-office.gov.uk>
Date: Mon, 12 Sep 2022 18:29:31 +0100
Subject: [PATCH 5/6] Deprecate $govuk-font-family-tabular

---
 src/govuk/helpers/typography.test.js     | 25 +++++++++++++++++++++---
 src/govuk/settings/_typography-font.scss | 10 ++++++++++
 2 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/src/govuk/helpers/typography.test.js b/src/govuk/helpers/typography.test.js
index f636b66dfc..dd40da3e85 100644
--- a/src/govuk/helpers/typography.test.js
+++ b/src/govuk/helpers/typography.test.js
@@ -407,9 +407,9 @@ describe('@mixin govuk-typography-responsive', () => {
         ${sassBootstrap}`
 
       await renderSass({ data: sass, ...sassConfig }).then(() => {
-        // Expect our mocked @warn function to have been called once with a single
-        // argument, which should be the deprecation notice
-        return expect(mockWarnFunction.mock.calls[0][0].getValue())
+        // Get the argument of the last @warn call, which we expect to be the
+        // deprecation notice
+        return expect(mockWarnFunction.mock.calls.at(-1)[0].getValue())
           .toEqual(
             '$govuk-typography-use-rem is deprecated. ' +
             'From version 5.0, GOV.UK Frontend will not support disabling rem font sizes'
@@ -597,3 +597,22 @@ describe('@mixin govuk-typography-responsive', () => {
     })
   })
 })
+
+describe('$govuk-font-family-tabular value is specified', () => {
+  it('outputs a deprecation warning when set', async () => {
+    const sass = `
+    $govuk-font-family-tabular: monospace;
+      ${sassBootstrap}`
+
+    await renderSass({ data: sass, ...sassConfig }).then(() => {
+      // Get the argument of the last @warn call, which we expect to be the
+      // deprecation notice
+      return expect(mockWarnFunction.mock.calls.at(-1)[0].getValue())
+        .toEqual(
+          '$govuk-font-family-tabular is deprecated. ' +
+          'From version 5.0, GOV.UK Frontend will not support using a separate ' +
+          'font-face for tabular numbers'
+        )
+    })
+  })
+})
diff --git a/src/govuk/settings/_typography-font.scss b/src/govuk/settings/_typography-font.scss
index 5e9028ce3a..63d66926a7 100644
--- a/src/govuk/settings/_typography-font.scss
+++ b/src/govuk/settings/_typography-font.scss
@@ -56,6 +56,8 @@ $govuk-font-family: if(
 ///
 /// @type List
 /// @access public
+/// @deprecated Will be removed in v5.0 with the rest of the compatibility mode
+/// suite of tools and settings
 
 $govuk-font-family-tabular: if(
   $govuk-use-legacy-font,
@@ -63,6 +65,14 @@ $govuk-font-family-tabular: if(
   false
 ) !default;
 
+// Only show the deprecation warning if user is setting $govuk-font-family-tabular
+// manually instead of automatically via $govuk-use-legacy-font
+@if $govuk-font-family-tabular != false and $govuk-use-legacy-font == false {
+  @warn "$govuk-font-family-tabular is deprecated. " +
+    "From version 5.0, GOV.UK Frontend will not support using a separate " +
+    "font-face for tabular numbers";
+}
+
 /// Font families to use for print media
 ///
 /// We recommend that you use system fonts when printing. This will avoid issues

From 2ccbba474ce4dbf8373f77075e8fde06aa4a6ceb Mon Sep 17 00:00:00 2001
From: owenatgov <owen.jones@digital.cabinet-office.gov.uk>
Date: Wed, 14 Sep 2022 12:35:45 +0100
Subject: [PATCH 6/6] Add changelog entry

---
 CHANGELOG.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c701e8adb7..a064506b1d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -72,6 +72,19 @@ This will enable screen reader users to have a better, more coherent experience
 
 This was added in [pull request #2677: Amend error summary markup to fix page load focus bug in JAWS 2022](https://github.com/alphagov/govuk-frontend/pull/2677).
 
+### Deprecated features
+
+#### Stop using settings associated with legacy codebases
+
+In GOV.UK Frontend v5.0 we will stop supporting compatibility with legacy codebases. As part of this, we are deprecating settings controlled by compatibility mode variables. This includes the `govuk-compatibility` mixin and the following settings:
+
+- `$govuk-use-legacy-palette`
+- `$govuk-use-legacy-font`
+- `$govuk-typography-use-rem`
+- `$govuk-font-family-tabular`
+
+This was introduced in [pull request #2844: Deprecate compatibility mode settings](https://github.com/alphagov/govuk-frontend/pull/2844).
+
 ### Fixes
 
 We’ve made fixes to GOV.UK Frontend in the following pull requests: