Merge pull request #5518 from alphagov/deprecate-govuk/all

Deprecate `govuk/all.scss` and only reference `govuk/index.scss` internally

.github/workflows/sass.yaml

@@ -38,12 +38,12 @@ jobs:
       - name: Run command
         run: |
           mkdir -p .tmp
-          time sass packages/govuk-frontend/src/govuk/all.scss > .tmp/all.css
+          time sass packages/govuk-frontend/src/govuk/index.scss > .tmp/index.css
 
       # Check output for uncompiled Sass
       - name: Check output
         run: |
-          ! grep "\$govuk-" .tmp/all.css
+          ! grep "\$govuk-" .tmp/index.css
 
   dart-sass-latest:
     name: Dart Sass v1 (latest)
@@ -73,12 +73,12 @@ jobs:
       - name: Run command
         run: |
           mkdir -p .tmp
-          time sh -c 'echo "@import "\""govuk/all"\"";" | sass --stdin --quiet-deps --load-path=packages/govuk-frontend/src > .tmp/all.css'
+          time sh -c 'echo "@import "\""govuk/all"\"";" | sass --stdin --quiet-deps --load-path=packages/govuk-frontend/src > .tmp/index.css'
 
       # Check output for uncompiled Sass
       - name: Check output
         run: |
-          ! grep "\$govuk-" .tmp/all.css
+          ! grep "\$govuk-" .tmp/index.css
 
   # Node Sass v5.0.0 = LibSass v3.5.5
   lib-sass:
@@ -107,12 +107,12 @@ jobs:
       - name: Run command
         run: |
           mkdir -p .tmp
-          time node-sass packages/govuk-frontend/src/govuk/all.scss > .tmp/all.css
+          time node-sass packages/govuk-frontend/src/govuk/index.scss > .tmp/index.css
 
       # Check output for uncompiled Sass
       - name: Check output
         run: |
-          ! grep "\$govuk-" .tmp/all.css
+          ! grep "\$govuk-" .tmp/index.css
 
   # Node Sass v8.x = LibSass v3 latest
   lib-sass-latest:
@@ -137,12 +137,12 @@ jobs:
       - name: Run command
         run: |
           mkdir -p .tmp
-          time node-sass packages/govuk-frontend/src/govuk/all.scss > .tmp/all.css
+          time node-sass packages/govuk-frontend/src/govuk/index.scss > .tmp/index.css
 
       # Check output for uncompiled Sass
       - name: Check output
         run: |
-          ! grep "\$govuk-" .tmp/all.css
+          ! grep "\$govuk-" .tmp/index.css
 
   ruby-sass:
     name: Ruby Sass v3.4.0 (deprecated)
@@ -165,12 +165,12 @@ jobs:
       - name: Run command
         run: |
           mkdir -p .tmp
-          time sass packages/govuk-frontend/src/govuk/all.scss > .tmp/all.css
+          time sass packages/govuk-frontend/src/govuk/index.scss > .tmp/index.css
 
       # Check output for uncompiled Sass
       - name: Check output
         run: |
-          ! grep "\$govuk-" .tmp/all.css
+          ! grep "\$govuk-" .tmp/index.css
 
   ruby-sass-latest:
     name: Ruby Sass v3 (latest, deprecated)
@@ -193,9 +193,9 @@ jobs:
       - name: Run command
         run: |
           mkdir -p .tmp
-          time sass packages/govuk-frontend/src/govuk/all.scss > .tmp/all.css
+          time sass packages/govuk-frontend/src/govuk/index.scss > .tmp/index.css
 
       # Check output for uncompiled Sass
       - name: Check output
         run: |
-          ! grep "\$govuk-" .tmp/all.css
+          ! grep "\$govuk-" .tmp/index.css

CHANGELOG.md

@@ -19,6 +19,20 @@ We introduced this change in:
 - [#5499: Rename GOVUKFrontendComponentConfigurable, export ConfigurableComponent](https://github.com/alphagov/govuk-frontend/pull/5499)
 - [#5456: Refactor Accordion to extend from a GOVUKFrontendConfigurableComponent](https://github.com/alphagov/govuk-frontend/issues/5456)
 
+### Deprecated features
+
+#### Importing Sass using `govuk/all`
+
+You'll see a warning when compiling your Sass if you import all of GOV.UK Frontend's styling using `govuk/all`. Importing using the `all` file is deprecated, and we’ll remove it in the next major release.
+
+In your import statements, use a trailing `/index` rather than `/all` to load GOV.UK Frontend's files:
+
+- `@import "govuk/index";` instead of `@import "govuk/all";`;
+
+You do not need `/index` at the end of each import path if you’re using Dart Sass.
+
+This change was introduced in [pull request #5518: Deprecate `govuk/all.scss` and only reference `govuk/index.scss` internally](https://github.com/alphagov/govuk-frontend/pull/5518).
+
 ## v5.7.1 (Fix release)
 
 To install this version with npm, run `npm install [email protected]`. You can also find more information about [how to stay up to date](https://frontend.design-system.service.gov.uk/staying-up-to-date/#updating-to-the-latest-version) in our documentation.

docs/contributing/coding-standards/components.md

@@ -12,7 +12,7 @@ When creating your component, you should create the following files in the compo
 
 - `README.md` - Summary documentation with links to the installation instructions and component documentation on <https://design-system.service.gov.uk/>
 - `_[component-name].scss` - An SCSS file to generate the styles for this component only. It delegates the CSS generation to the \_index.scss file.
-- `_index.scss` - The actual styles for the component that you can import in 2 ways - [on their own using `[component-name].scss`](https://frontend.design-system.service.gov.uk/importing-css-assets-and-javascript/#import-specific-parts-of-the-css) or [alongside other components in `components/_all.scss`](https://frontend.design-system.service.gov.uk/importing-css-assets-and-javascript/#import-specific-parts-of-the-css)
+- `_index.scss` - The actual styles for the component that you can import in 2 ways - [on their own using `[component-name].scss`](https://frontend.design-system.service.gov.uk/importing-css-assets-and-javascript/#import-specific-parts-of-the-css) or [alongside other components in `components/_index.scss`](https://frontend.design-system.service.gov.uk/importing-css-assets-and-javascript/#import-specific-parts-of-the-css)
 - `[component-name].yaml` - Lists the component's Nunjucks macro options and includes examples using these options. Both the options and examples are used to generate component documentation in the review app. The examples are also used to test component behaviour, and to generate [fixtures for testing alternative implementations of the design system](https://frontend.design-system.service.gov.uk/testing-your-html/).
 - `macro.njk` - The main entry point for rendering the component. It provides a `govuk[ComponentName](params)` macro, delegating render to the `template.njk` file
 - `template.njk` - The template used for rendering the component using any `params` provided to the macro

packages/govuk-frontend-review/src/stylesheets/app.scss

@@ -4,7 +4,7 @@ $govuk-new-organisation-colours: true;
 
 $govuk-suppressed-warnings: ("organisation-colours");
 
-@import "govuk/all";
+@import "govuk";
 @import "partials/app";
 @import "partials/code";
 @import "partials/banner";

packages/govuk-frontend-review/tasks/watch.mjs

@@ -43,7 +43,7 @@ function getTasks(options) {
     ),
     'compile:scss watch': () =>
       gulp.watch(
-        ['**/*.scss', join(paths.package, 'dist/govuk/all.scss')],
+        ['**/*.scss', join(paths.package, 'dist/govuk/index.scss')],
         {
           awaitWriteFinish: true,
           cwd: options.srcPath,

packages/govuk-frontend/package.json

@@ -4,7 +4,7 @@
   "version": "5.7.1",
   "main": "dist/govuk/all.bundle.js",
   "module": "dist/govuk/all.mjs",
-  "sass": "dist/govuk/all.scss",
+  "sass": "dist/govuk/index.scss",
   "files": [
     "dist",
     "govuk-prototype-kit.config.json",
@@ -13,7 +13,7 @@
   ],
   "exports": {
     ".": {
-      "sass": "./dist/govuk/all.scss",
+      "sass": "./dist/govuk/index.scss",
       "import": "./dist/govuk/all.mjs",
       "require": "./dist/govuk/all.bundle.js",
       "default": "./dist/govuk/all.bundle.js"

packages/govuk-frontend/src/govuk/all.scss

@@ -1 +1,7 @@
 @import "index";
+
+@include _warning(
+  "import-using-all",
+  "Importing using 'govuk/all' is deprecated. Update your import statement to import 'govuk/index'.",
+  $silence-further-warnings: false
+);

packages/govuk-frontend/src/govuk/all.unit.test.mjs

@@ -114,6 +114,20 @@ describe('GOV.UK Frontend', () => {
       }
     })
 
+    it('outputs a warning when importing the "all" file at root', async () => {
+      const sass = `
+      @import "all";
+      `
+
+      await compileSassString(sass, sassConfig)
+
+      expect(mockWarnFunction.mock.calls[0]).toEqual(
+        expect.arrayContaining([
+          `Importing using 'govuk/all' is deprecated. Update your import statement to import 'govuk/index'. To silence this warning, update $govuk-suppressed-warnings with key: "import-using-all"`
+        ])
+      )
+    })
+
     it('outputs a warning for each layer that has an "all" file', async () => {
       const sass = `
       /* equivalent to importing 'base' */

packages/govuk-frontend/tasks/build/package.unit.test.mjs

@@ -109,8 +109,8 @@ describe('packages/govuk-frontend/dist/', () => {
 
       // Only sass package entry is compiled to minified CSS bundle
       .flatMap(
-        mapPathTo(['**/govuk/all.scss'], ({ dir: requirePath }) => [
-          join(requirePath, 'all.scss'),
+        mapPathTo(['**/govuk/index.scss'], ({ dir: requirePath }) => [
+          join(requirePath, 'index.scss'),
 
           // CSS bundle, minified
           join(requirePath, 'govuk-frontend.min.css'),
@@ -163,6 +163,15 @@ describe('packages/govuk-frontend/dist/', () => {
   })
 
   describe('Sass stylesheets', () => {
+    describe('index.scss', () => {
+      it('should compile without throwing an exception', async () => {
+        const file = join(paths.package, 'dist/govuk/index.scss')
+        await expect(compileSassFile(file)).resolves.not.toThrow()
+      })
+    })
+
+    // all.scss is deprecated but we still want to make sure it works when used
+    // as the root for compilation
     describe('all.scss', () => {
       it('should compile without throwing an exception', async () => {
         const file = join(paths.package, 'dist/govuk/all.scss')

packages/govuk-frontend/tasks/build/release.mjs

@@ -46,7 +46,7 @@ export default (options) =>
 
     // Compile GOV.UK Frontend Sass
     task.name('compile:scss', () =>
-      styles.compile('all.scss', {
+      styles.compile('index.scss', {
         ...options,
 
         srcPath: join(options.srcPath, 'govuk'),

packages/govuk-frontend/tasks/build/release.unit.test.mjs

@@ -81,7 +81,7 @@ describe('dist/', () => {
 
     it('should contain relative paths to sources', () => {
       expect(sourcemap.sources).toContain(
-        '../packages/govuk-frontend/src/govuk/all.scss'
+        '../packages/govuk-frontend/src/govuk/index.scss'
       )
       expect(sourcemap.sources).toContain(
         '../packages/govuk-frontend/src/govuk/core/_govuk-frontend-properties.scss'

packages/govuk-frontend/tasks/styles.mjs

@@ -15,7 +15,7 @@ export const compile = (options) =>
      * Compile GOV.UK Frontend Sass
      */
     task.name('compile:scss', () =>
-      styles.compile('all.scss', {
+      styles.compile('index.scss', {
         ...options,
 
         srcPath: join(options.srcPath, 'govuk'),