From a9bccd2bb5b664842be14c1a6b8e6c39de3f4a1a Mon Sep 17 00:00:00 2001 From: Romaric Pascal Date: Fri, 8 Dec 2023 11:27:20 +0000 Subject: [PATCH 1/5] Add release notes draft to the CHANGELOG --- CHANGELOG.md | 682 +++++++++++++++++++++++++++++---------------------- 1 file changed, 394 insertions(+), 288 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f704a73c07..94b6047ce6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,197 +4,258 @@ For advice on how to use these release notes see [our guidance on staying up to ## Unreleased -## 5.0.0-beta.2 (Pre-release) +You can find a summary of the main [changes to GOV.UK Frontend v5](https://frontend.design-system.service.gov.uk/changes-to-govuk-frontend-v5/) on the Frontend site. It's important to note [our old frameworks (such as GOV.UK Elements)](https://frontend.design-system.service.gov.uk/v4/migrating-from-legacy-products/) are no longer compatible with this release. It also stops Internet Explorer 11 from running GOV.UK Frontend JavaScript and removes support completely for Internet Explorer 8 to 10. + +Your service will not stop working in Internet Explorer 11, but components will look and behave differently without JavaScript. Read more about [how we provide support for different browsers](https://release-5-0--govuk-frontend-docs-preview.netlify.app/browser-support/). + +Service teams should be [using a progressive enhancement approach](https://www.gov.uk/service-manual/technology/using-progressive-enhancement) to make sure users can still access any content and complete their tasks. + +If you still need to provide support for older versions of Internet Explorer, you should stay on the latest [GOV.UK Frontend v4 release](https://github.com/alphagov/govuk-frontend/releases). ### Breaking changes -#### Update the GOV.UK logo +You must make the following changes when you migrate to this release, or your service might break. -The GOV.UK logo has been updated to merge the GOV.UK text with the crown graphic. This is to ensure that the full logo is always rendered correctly even if parts of the page, such as CSS or the Transport webfont fail to load. Styles relating to the logo have also been modified. +#### Update package file paths for Sass -If you're using the `govukHeader` Nunjucks macro you don't need to change anything. +In preparation for additional build targets, we've moved our package files into a directory called `dist`. -Otherwise, to update to the new logo: +Replace `govuk-frontend/govuk` with `govuk-frontend/dist/govuk` in any [Sass](https://sass-lang.com/) `@import` paths. -1. Remove `` and its content. -2. Remove the `` around the `svg` element. -3. Replace the `svg` element with [this updated SVG](https://github.com/alphagov/govuk-frontend/blob/06e6a56655f458112363423dc8f1fb50d21b225e/packages/govuk-frontend/src/govuk/components/header/template.njk#L14-L25), ensuring that the class name and attributes are also updated. +For example: -This change was made in [pull request #4449: Implement transitional crown in the Header component (v5.0)](https://github.com/alphagov/govuk-frontend/pull/4449). +```scss +@import "node_modules/govuk-frontend/dist/govuk/all"; +``` -#### Check your favicons, app icons and OpenGraph image still work +If you've added [`node_modules/govuk-frontend` as a Sass import path](https://frontend.design-system.service.gov.uk/importing-css-assets-and-javascript/#simplify-sass-import-paths), update it with the `/dist` suffix: -We've changed the names, formats and sizes of icon assets that we distribute in Frontend. You will want to check that the correct files are in place. +```js +loadPaths: [ +  'node_modules/govuk-frontend/dist' +] +``` -The following files have been added to the assets folder: +If you're building your Sass code through Rails Assets Pipeline or Sprockets, refer to the section 'Update package file paths in Rails Assets Pipeline or Sprockets'. -- manifest.json -- images/favicon.svg -- images/govuk-icon-180.png -- images/govuk-icon-192.png -- images/govuk-icon-512.png -- images/govuk-icon-mask.svg +Refer to the [detailed guidance on importing using Sass](https://release-5-0--govuk-frontend-docs-preview.netlify.app/importing-css-assets-and-javascript/#import-using-sass). -The following files have been removed from the assets folder: +These changes were introduced in [#3498: Remove built `dist` and `package` from source](https://github.com/alphagov/govuk-frontend/pull/3498) -- images/govuk-apple-touch-icon.png -- images/govuk-apple-touch-icon-152x152.png -- images/govuk-apple-touch-icon-167x167.png -- images/govuk-apple-touch-icon-180x180.png -- images/govuk-mask-icon.svg +#### Update package file paths for Nunjucks -If you're not using the Nunjucks page template, you will need to replace the list of icons in the template's `head` with the following: +In preparation for additional build targets, we've moved our package files into a directory called `dist`. -```html - - - - - +Replace `govuk-frontend` with `govuk-frontend/dist` in any [`nunjucks.configure()`](https://mozilla.github.io/nunjucks/api.html#configure) search paths: + +```js +nunjucks.configure([ +  'node_modules/govuk-frontend/dist' +]) ``` -You will need to update the file path to match your assets folder if it's not at the default location. +Refer to the [detailed guidance on using Nunjucks](https://release-5-0--govuk-frontend-docs-preview.netlify.app/use-nunjucks/#set-up-nunjucks-and-use-the-page-template). -This change was made in [pull request #4445: Implement transitional crown favicons (v5.0)](https://github.com/alphagov/govuk-frontend/pull/4445). +These changes were made in the following pull requests: -### Recommended changes +- [#3491: Update Review app to import `govuk-frontend` via local package](https://github.com/alphagov/govuk-frontend/pull/3491) +- [#3498: Remove built `dist` and `package` from source](https://github.com/alphagov/govuk-frontend/pull/3498) -We've recently made some non-breaking changes to GOV.UK Frontend. Implementing these changes will make your service work better. +#### Update package file paths for assets such as images and fonts  -#### Remove the X-UA-Compatible meta tag +In preparation for additional build targets, we've moved our package files into a directory called `dist`. -Remove the `` meta tag from your page template. +If you're [serving the assets from the GOV.UK Frontend assets folder](https://frontend.design-system.service.gov.uk/v4/importing-css-assets-and-javascript/#serve-the-assets-from-the-gov-uk-frontend-assets-folder-recommended) (`node_modules/govuk-frontend/govuk/assets`), [update your routing to the new assets path ](https://frontend.design-system.service.gov.uk/importing-css-assets-and-javascript/#serve-the-assets-from-the-gov-uk-frontend-assets-folder-recommended): `node_modules/govuk-frontend/dist/govuk/assets`. -Internet Explorer versions 8, 9 and 10 included a feature that would try to determine if the page was built for an older version of IE and would silently enable compatibility mode, which would modify the rendering engine's behaviour to match the older version of IE. Setting this meta tag prevented that behaviour. +Refer to the [detailed guidance on importing assets](https://release-5-0--govuk-frontend-docs-preview.netlify.app/importing-css-assets-and-javascript/#font-and-image-assets). -IE11 deprecated this meta tag and defaulted to always using IE11's renderer when the page has a HTML5 doctype (``). +These changes were introduced in [#3498: Remove built `dist` and `package` from source](https://github.com/alphagov/govuk-frontend/pull/3498) -As Frontend no longer supports Internet Explorer versions older than 11, this meta tag can now be removed. +#### Update package file paths in Rails Assets Pipeline or Sprockets -This change was made in [pull request #4434: Remove X-UA-Compatible meta tag](https://github.com/alphagov/govuk-frontend/pull/4434). +In preparation for additional build targets, we've moved our package files into a directory called `dist`. -### Fixes +Update the  `node_modules/govuk-frontend` part of the path to `node_modules/govuk-frontend/dist`, if you've added the path to GOV.UK Frontend package inside `node_modules` to: -We’ve made fixes to GOV.UK Frontend in the following pull requests: +- [Rails Assets Pipeline search path](https://guides.rubyonrails.org/asset_pipeline.html#search-paths) using `Rails.application.config.assets.paths` +- Sprockets using `append_path` -- [#4416: Review and fix HTML attribute trailing spaces etc](https://github.com/alphagov/govuk-frontend/pull/4416) -- [#4444: Fix UMD component exports with duplicate names](https://github.com/alphagov/govuk-frontend/pull/4444) -- [#4492: Improve SupportError when `` is not set](https://github.com/alphagov/govuk-frontend/pull/4492) -- [#4450: Update descriptions for Nunjucks macro options + fixes](https://github.com/alphagov/govuk-frontend/pull/4450) +These changes were introduced in [#3498: Remove built `dist` and `package` from source](https://github.com/alphagov/govuk-frontend/pull/3498) -## 5.0.0-beta.1 (Pre-release) +#### Update package file paths if including JavaScript directly -### Fixes +In preparation for additional build targets, we've moved our package files into a directory called `dist`. -We’ve made fixes to GOV.UK Frontend in the following pull requests: +If you've [set up your routing to serve GOV.UK Frontend's `all.js` file from `node_modules`](https://release-5-0--govuk-frontend-docs-preview.netlify.app/v4/importing-css-assets-and-javascript/#add-the-javascript-file-to-your-html), update the path you're serving to `node_modules/govuk-frontend/dist/govuk/govuk-frontend.min.js`. -- [#4391: Move private workspace packages to `devDependencies`](https://github.com/alphagov/govuk-frontend/pull/4391) -- [#4394: Improve SupportError when document.body is not set](https://github.com/alphagov/govuk-frontend/pull/4394) +Update any ` +``` -### New features +Replace `` to import and initialise GOV.UK Frontend using ES modules: -#### Added a new Task list component +```html + +``` -Each task in the list can have a title, status, link and an optional hint. When a link is added, the whole row is clickable. +Refer to the [detailed guidance on importing JavaScript](. -This change was made in [pull request #2261: Task list component](https://github.com/alphagov/govuk-frontend/pull/2261). +These changes were introduced in [#3498: Remove built `dist` and `package` from source](https://github.com/alphagov/govuk-frontend/pull/3498) -#### Added focus style for links containing non-text content +#### Update package file paths for Node.js and other bundlers -We've added a new focus style for use with non-text content, such as links containing images and focusable elements that are not form controls. This new style paints a visible yellow and black outline around the entire element, ensuring the focus style is visible in all situations. +In preparation for additional build targets, we've moved our package files into a directory called `dist`. -For links containing images, we've added the `govuk-link-image` class. You should only use this class on links containing an image. If it also contains text, continue to use `govuk-link` instead. +If you're importing GOV.UK Frontend using `import ... from 'govuk-frontend'` or `require('govuk-frontend')`, you have nothing to change. -```html - - ... - +If you're using `import` to import individual components, replace `govuk-frontend/govuk` with `govuk-frontend/dist/govuk`. For example: + +```js +import Button from 'govuk-frontend/dist/govuk/components/button/button.mjs' ``` -You can use these styles in your own code by including the `govuk-focused-box` Sass mixin. +If you're using `require` to import individual components, replace `govuk-frontend/govuk` with `govuk-frontend/dist/govuk` and update the file name to `.bundle.js`. For example: -This change was made in [pull request #3819: Add linked image focus style](https://github.com/alphagov/govuk-frontend/pull/3819). +```js +const Button = require('govuk-frontend/dist/govuk/components/button/button.bundle.js') +``` -#### New link styles are now enabled by default +Refer to the [detailed guidance on importing JavaScript](https://release-5-0--govuk-frontend-docs-preview.netlify.app/importing-css-assets-and-javascript/#import-javascript-using-a-bundler). -In GOV.UK Frontend v3.12.0 we introduced new link styles which are now enabled by default. They have: +These changes were introduced in [#3498: Remove built `dist` and `package` from source](https://github.com/alphagov/govuk-frontend/pull/3498) -underlines that are consistently thinner and a bit further away from the link text -a clearer hover state, where the underline gets thicker to make the link stand out to users +#### Verify your code does not rely on polyfills we have now removed -The new link styles are now enabled by default. If you are setting `$govuk-new-link-styles` to `true` in your Sass you can now remove this. +We have removed polyfills for Internet Explorer 8 to 11: -This change was made in: +- `DOMTokenList`, `Element.prototype.classList`, `Element.prototype.closest`, `Element.prototype.matches`, and `Event` - required for Internet Explorer 11 and below +- `Element.prototype.dataset` - required for Internet Explorer 10 and below +- `Date.now`, `Document`, `Element`, `Element.prototype.nextElementSibling`, `Element.prototype.previousElementSibling`, `Function.prototype.bind`, `Object.defineProperty`, `String.prototype.trim` and `Window` - required for Internet Explorer 8 -- [pull request #3599: Enable new link styles by default](https://github.com/alphagov/govuk-frontend/pull/3599) -- [pull request #3600: Remove new link styles feature flag](https://github.com/alphagov/govuk-frontend/pull/3600) +However, because these polyfills create or extend global objects ('polluting the global namespace'), you might have other code in your service unintentionally relying on the inclusion of these polyfills. You might need to introduce your own polyfills or rewrite your JavaScript to avoid using the polyfilled features. -#### Customise inverse button colours +These changes were introduced in [pull request #3570: Remove Internet Explorer 8 to 10 JavaScript polyfills, helpers, config](https://github.com/alphagov/govuk-frontend/pull/3570) -For non-GOV.UK branded websites, you can now change the colours of inverse buttons - buttons intended for use on dark backgrounds. +#### Stop Internet Explorer 11 and other older browsers running unsupported JavaScript -To change the inverse button's background colour, set the `$govuk-inverse-button-background-colour` Sass variable. +Add `type="module"` to all HTML ` ``` -This change was made in [pull request #4043: Add ability to customise inverse button colours](https://github.com/alphagov/govuk-frontend/pull/4043). +with: -#### Precompiled CSS and JavaScript +```js + +``` -The precompiled CSS and JavaScript files found in our [GitHub releases](https://github.com/alphagov/govuk-frontend/releases) are now also published to [`govuk-frontend` on npm](https://www.npmjs.com/package/govuk-frontend). +These changes were introduced in [pull request #3801: -These changes were introduced in: +Add class .govuk-frontend-supported for ES modules support] () -- [pull request #3726: Default to ES modules with single Rollup config](https://github.com/alphagov/govuk-frontend/pull/3726) -- [pull request #4241: Add new `govuk-frontend.min.css` package bundle](https://github.com/alphagov/govuk-frontend/pull/4241) +#### Update the hash used by your Content Security Policy -#### Check your tags align with design changes to the Tag component +If your [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) uses a hash to let the snippet above run, you'll need to update it from: + +``` +sha256-+6WnXIl4mbFTCARd8N3COQmT3bJJmo32N8q8ZSQAIcU= +``` -We’ve changed the design of the tag component to improve accessibility and readability. +to: -Text within the tag is no longer bold and uppercase with extra letter spacing. It’s now regular 19px text with the first letter of a word capitalised and the rest of the content lowercase. Due to this, there might be changes to the width of existing tags. +``` +sha256-GUQ5ad8JK5KmEWmROf3LZd9ge94daqNvd8xy9YS1iDw= +``` -The colours have also changed to make them more distinguishable from buttons. +These changes were introduced in [pull request #3801: -Check your service is using the correct capitalisation in the contents of tags and tags within phase banners. +Add class .govuk-frontend-supported for ES modules support] () -This change was made in: +#### Remove calls to component `init` methods from your JavaScript -- [pull request #3502: Tag design changes](https://github.com/alphagov/govuk-frontend/pull/3502) -- [pull request #3731: Remove the first letter modifier from the tag component](https://github.com/alphagov/govuk-frontend/pull/3731) +If you instantiate individual components, remove any calls to component `init` methods,  as initialisation now happens automatically. If you initialise the JavaScript using `window.GOVUKFrontend.initAll()`, you will not need to make any changes. -### Breaking changes +For example, the following: -You must make the following changes when you migrate to this release, or your service might break. +```js +new Radios($radio).init() +``` + +becomes: + +```js +new Radios($radio) +``` + +This change was introduced in [pull request #4011: Remove component init() methods and initialise in constructor](https://github.com/alphagov/govuk-frontend/pull/4011). + +#### Remove Internet Explorer 8 stylesheets, settings and mixins -#### "Compatibility mode" features are no longer supported +We no longer support Internet Explorer 8 (IE8) in GOV.UK Frontend or provide dedicated stylesheets for the browser. Remove any references to these stylesheets from your HTML. + +We've removed the `govuk-if-ie8` and `govuk-not-ie8` mixins, and the `$govuk-is-ie8` and `$govuk-ie8-breakpoint` settings. These were deprecated in [GOV.UK Frontend v4.6.0](https://github.com/alphagov/govuk-frontend/releases/tag/v4.6.0). + +You should: + +- remove calls to the `govuk-if-ie8` mixin entirely (because the code passed to the mixin was only ever for Internet Explorer 8) +- replace calls to the `govuk-not-ie8` mixin with the contents that were previously passed to the mixin (because now we always want the code passed to the mixin) +- verify your codebase no longer uses these mixins and variables +- remove `ie8` from the `$govuk-suppressed-warnings` list, if present + +If a library you depend on is not yet updated and relies on these mixins and variables, as a temporary workaround you can define the following mixins and variables before importing: + +```scss +$govuk-is-ie8: false; +$govuk-ie8-breakpoint: ('desktop'); +@mixin govuk-if-ie8 {} +@mixin govuk-not-ie8 {@content} +``` + +This change was introduced in [pull request #3559: Remove IE8-related Sass and CSS build tasks](https://github.com/alphagov/govuk-frontend/pull/3559). + +#### Remove references to "Compatibility mode" and related features from your Sass -GOV.UK Frontend no longer supports compatibility with our old frameworks: +GOV.UK Frontend is no longer compatible with [our old frameworks](https://frontend.design-system.service.gov.uk/v4/migrating-from-legacy-products/): - GOV.UK Elements - GOV.UK Template - GOV.UK Frontend Toolkit. -You can no longer incrementally add GOV.UK Frontend to an existing service using one of these previous frameworks. We have removed the following Sass variables and one mixin which controlled compatibility mode: +You cannot migrate an existing service to GOV.UK Frontend v5.0 if it is still using one of these frameworks -- you'll need to remain on the latest v4.x release until you've finished the migration. Remove any references to these Sass variables and mixins: - `$govuk-compatibility-govukelements` - `$govuk-compatibility-govuktemplate` - `$govuk-compatibility-govukfrontendtoolkit` -- the `compatibility-mode` mixin which automatically checked if any of the 3 control variables were set to `true` -We’ve additionally removed features that were managed using the above variables. The following features and their corresponding variables have now been removed: +- the `govuk-compatibility` mixin which could be used to conditionally output CSS when compatibility mode was enabled +- remove `compatibility-mode` from the `$govuk-suppressed-warnings` list, if present + +We've additionally removed features that were managed using the above variables. We've removed the following features and their corresponding variables: - access to the legacy colour palette using `$govuk-use-legacy-palette` - access to the legacy font using `$govuk-use-legacy-font` @@ -209,315 +270,329 @@ These changes were introduced in: - [pull request #3574: Remove legacy and tabular fonts support](https://github.com/alphagov/govuk-frontend/pull/3574) - [pull request #3576: Remove $govuk-typography-use-rem setting](https://github.com/alphagov/govuk-frontend/pull/3575) -#### Update the HTML for warning text +#### Remove references to font family variables from your Sass -We've removed the `.govuk-warning-text__assistive` class and its styles from GOV.UK Frontend. This class is unnecessary, as it duplicates the functionality of the `.govuk-visually-hidden` class already present in Frontend. +Remove any references to following Sass variables: -If you’re not using Nunjucks macros, update your warning text HTML to replace the `govuk-warning-text__assistive` class with the `govuk-visually-hidden` class. +- `$govuk-font-family-gds-transport` +- `$govuk-font-family-nta` +- `$govuk-font-family-nta-tabular` -This change was introduced in [pull request #3569: Remove unnecessary class from Warning Text component](https://github.com/alphagov/govuk-frontend/pull/3569). +If you were using `$govuk-font-family-gds-transport` to set the font on an element, we recommend using [the `govuk-font` mixin](https://frontend.design-system.service.gov.uk/sass-api-reference/#govuk-font) instead. -#### Update package file paths +This change was introduced in [pull request #3949: Simplify font family settings](https://github.com/alphagov/govuk-frontend/pull/3949). -In preparation for additional build targets, we've moved our package files into a directory called `dist`. +#### Remove references to `govuk-button--disabled` class from the HTML for the Button component -##### If you’re using Node.js and other bundlers +For the [Button component](https://design-system.service.gov.uk/components/button/), remove any references to the `govuk-button--disabled` class that we deprecated in [GOV.UK Frontend v4.6.0](https://github.com/alphagov/govuk-frontend/releases/tag/v4.6.0). -Replace `govuk-frontend/govuk` with `govuk-frontend/dist/govuk` in any JavaScript `require()` or `import` file paths. +Use the `disabled` attribute to mark `