diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index f0039520d..09530b690 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,7 +1,7 @@ # PR Checklist - [ ] If you are proposing a new decision record document, used the right template for that - - ([ADR](https://github.com/alphagov/forms/blob/main/ADR/ADRXXX-architecture-decision-record-template.md), [decision-record](https://github.com/alphagov/forms/blob/main/decision-record/DRXXX-decision-record-template.md), engagement, [research](https://github.com/alphagov/forms/blob/main/research/YYYY-MM-DD-template.md)) + - ([ADR](https://github.com/govuk-forms/forms/blob/main/ADR/ADRXXX-architecture-decision-record-template.md), [decision-record](https://github.com/govuk-forms/forms/blob/main/decision-record/DRXXX-decision-record-template.md), engagement, [research](https://github.com/govuk-forms/forms/blob/main/research/YYYY-MM-DD-template.md)) - [ ] Set yourself as the Assignee - [ ] Tag anyone you would like to review, or @forms-design or @forms-devs - [ ] Fill in the template below diff --git a/ADR/ADR049-remove-user-research-environment.md b/ADR/ADR049-remove-user-research-environment.md new file mode 100644 index 000000000..a6347fde2 --- /dev/null +++ b/ADR/ADR049-remove-user-research-environment.md @@ -0,0 +1,36 @@ +ADR049: Remove user research environment + +Date: 2026-04-16 + +## Status + +Accepted + +## Context + +We run a separate user research (UR) environment: a copy of GOV.UK Forms in its own AWS account. It used to cost about $850 per month; after reducing database spend it now costs about $350 per month ($4,200 per year). There is little further scope to reduce costs without removing parts of the infrastructure, which creates overhead before we can start using it. + +We have not used it in the last 12 months, and there are no plans to use it in the short term. + +We have also built pull request (PR) preview environments, which provide a convenient way to see and interact with changes before they are merged. + +The main benefits of the UR environment were that it was isolated from other environments, could be kept stable (protected from change) while we conducted user research, and allowed testing of larger changes (e.g. deploying multiple applications or changes to infrastructure). + +We also have dev environment which is seperate to our deployment pipeline (i.e. not staging and production). It could be used in lieu of the UR environment. + +## Decision + +We will remove the user research environment and its AWS infrastructure. + +The ongoing cost in money, maintenance time, and operational overhead is now disproportionate to the value it delivers, especially given recent usage. + +If and when we need we could do the following: +- freeze deployments to the dev environment when we need a stable environment for research +- use PR preview environments for smaller, single app changes +- improve preview environments to support more complex multi-app or infrastructure changes where needed + +## Consequences + +- Saves about $350 per month ($4,200 per year). +- Reduces operational overhead and platform complexity. +- Means some larger changes will need more coordination to run UR in dev, or further investment in preview environments. diff --git a/README.md b/README.md index 2b0cfc763..097fc45b6 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # GOV.UK Forms +GOV.UK Forms is a platform that makes it easy for government service teams to create accessible online forms. You can find out more about it on our product site: [www.gov.uk/forms](https://www.forms.service.gov.uk/) + +## This repository + We record our work and decisions in this repo. You can find: @@ -10,18 +14,18 @@ You can find: - user research findings in [research/](research/) - documentation of our designs in [design/](design/) -## Our repositories +## Our other repositories You can find our code in the following repositories: -- [forms-admin](https://github.com/alphagov/forms-admin) - our application for building forms. -- [forms-runner](https://github.com/alphagov/forms-runner) - our application for hosting forms, so that they can be filled in by members of the public. -- [forms-e2e-tests](https://github.com/alphagov/forms-e2e-tests) - end-to-end tests for the service. -- [forms-product-page](https://github.com/alphagov/forms-product-page) - our product pages, as seen at [https://forms.service.gov.uk](https://forms.service.gov.uk) -- [forms-prototypes](https://github.com/alphagov/forms-prototypes) - our prototypes, used for user research and design exploration. -- [govuk-forms-markdown](https://github.com/alphagov/govuk-forms-markdown) - our gem for rendering the limited subset of markdown we support. +- [forms-admin](https://github.com/govuk-forms/forms-admin) - our application for building forms. +- [forms-runner](https://github.com/govuk-forms/forms-runner) - our application for hosting forms, so that they can be filled in by members of the public. +- [forms-e2e-tests](https://github.com/govuk-forms/forms-e2e-tests) - end-to-end tests for the service. +- [forms-product-page](https://github.com/govuk-forms/forms-product-page) - our product pages, as seen at [https://forms.service.gov.uk](https://forms.service.gov.uk) +- [forms-prototypes](https://github.com/govuk-forms/forms-prototypes) - our prototypes, used for user research and design exploration. +- [govuk-forms-markdown](https://github.com/govuk-forms/govuk-forms-markdown) - our gem for rendering the limited subset of markdown we support. We also have: -- [a private wiki](https://github.com/alphagov/forms-team/wiki) for team documentation (set-up, onboarding etc) +- [a private wiki](https://github.com/govuk-forms/forms-team/wiki) for team documentation (set-up, onboarding etc) ## License diff --git a/decision-record/README.md b/decision-record/README.md index 906e0c0ef..305405076 100644 --- a/decision-record/README.md +++ b/decision-record/README.md @@ -14,7 +14,7 @@ Proposing and reviewing decisions requires an understanding of the GitHub and [p ## Reviewing a decision -1. Find the decision record in the list of [pull requests](https://github.com/alphagov/forms/pulls) +1. Find the decision record in the list of [pull requests](https://github.com/govuk-forms/forms/pulls) 2. Add a comment and / or approve the pull request ## Approving / superseding / rejecting a decision diff --git a/design/features/README.md b/design/features/README.md index fa22f676f..64ffae8ef 100644 --- a/design/features/README.md +++ b/design/features/README.md @@ -44,4 +44,8 @@ Asks form creator users for consent to send an email to them about user research Allows form creators to create 2 branches of questions or to skip someone to a later question, or an exit page, based on an answer to a radio question. ### [User management journey](user-management) -Gives organisations more control over who can create forms and who can make them live. +Gives organisations more control over who can create forms and who can make them live. + +### [Welsh version pages](welsh-version) +Allows form creators to add a Welsh version of their form as part of their English version. + diff --git a/design/features/add-answer-for-none-of-the-above/README.md b/design/features/add-answer-for-none-of-the-above/README.md new file mode 100644 index 000000000..e388f7ecd --- /dev/null +++ b/design/features/add-answer-for-none-of-the-above/README.md @@ -0,0 +1,24 @@ +# Let people add an answer if ‘none of the above’ is selected + +## Contents + +- [What](#what) +- [Why](#why) + +--- + +## What + +This feature lets form creators ask form fillers to enter an answer if they’ve selected ‘none of the above’ from a selection list question. + +Form creators can choose whether it’s mandatory or optional for form fillers to provide an answer if they’ve selected ‘none of the above’. + +## Why + +It’s a requested feature that people expect a form builder to have. We expect it to increase the number of forms and submissions, and to have a positive impact on user satisfaction. + +At least 5 departments had expressed interest in this feature. We’d also received at least 5 anonymous feedback tickets about it from our feedback link by the time we started the work. + +The need for this feature came up as part of the ‘select from a long list’ work, as we were adding a ‘None of the above’ option to autocomplete. + +Usability testing suggested that some people expected to be able to add an option for ‘Other’ followed by a text box where they could enter more information. diff --git a/design/features/add-answer-for-none-of-the-above/Screenshots/001-create-list-of-options-page-new-radio.png b/design/features/add-answer-for-none-of-the-above/Screenshots/001-create-list-of-options-page-new-radio.png new file mode 100644 index 000000000..747333310 Binary files /dev/null and b/design/features/add-answer-for-none-of-the-above/Screenshots/001-create-list-of-options-page-new-radio.png differ diff --git a/design/features/add-answer-for-none-of-the-above/Screenshots/002-ask-for-an-answer-page.png b/design/features/add-answer-for-none-of-the-above/Screenshots/002-ask-for-an-answer-page.png new file mode 100644 index 000000000..c0cf7db5a Binary files /dev/null and b/design/features/add-answer-for-none-of-the-above/Screenshots/002-ask-for-an-answer-page.png differ diff --git a/design/features/add-answer-for-none-of-the-above/Screenshots/003-edit-question-page.png b/design/features/add-answer-for-none-of-the-above/Screenshots/003-edit-question-page.png new file mode 100644 index 000000000..cfe1dee82 Binary files /dev/null and b/design/features/add-answer-for-none-of-the-above/Screenshots/003-edit-question-page.png differ diff --git a/design/features/add-answer-for-none-of-the-above/Screenshots/004-your-questions-page.png b/design/features/add-answer-for-none-of-the-above/Screenshots/004-your-questions-page.png new file mode 100644 index 000000000..66fb978e9 Binary files /dev/null and b/design/features/add-answer-for-none-of-the-above/Screenshots/004-your-questions-page.png differ diff --git a/design/features/add-answer-for-none-of-the-above/Screenshots/005-submission-email.png b/design/features/add-answer-for-none-of-the-above/Screenshots/005-submission-email.png new file mode 100644 index 000000000..1ca17843c Binary files /dev/null and b/design/features/add-answer-for-none-of-the-above/Screenshots/005-submission-email.png differ diff --git a/design/features/add-answer-for-none-of-the-above/Screenshots/006-CSV-file.png b/design/features/add-answer-for-none-of-the-above/Screenshots/006-CSV-file.png new file mode 100644 index 000000000..1eb57528c Binary files /dev/null and b/design/features/add-answer-for-none-of-the-above/Screenshots/006-CSV-file.png differ diff --git a/design/features/add-answer-for-none-of-the-above/Screenshots/007-JSON-file.png b/design/features/add-answer-for-none-of-the-above/Screenshots/007-JSON-file.png new file mode 100644 index 000000000..58f2d8a84 Binary files /dev/null and b/design/features/add-answer-for-none-of-the-above/Screenshots/007-JSON-file.png differ diff --git a/design/features/add-answer-for-none-of-the-above/Screenshots/008-form-filler-additional-question-view.png b/design/features/add-answer-for-none-of-the-above/Screenshots/008-form-filler-additional-question-view.png new file mode 100644 index 000000000..7cd3f4d63 Binary files /dev/null and b/design/features/add-answer-for-none-of-the-above/Screenshots/008-form-filler-additional-question-view.png differ diff --git a/design/features/add-answer-for-none-of-the-above/Screenshots/009-form-filler-autocomplete-question-view.png b/design/features/add-answer-for-none-of-the-above/Screenshots/009-form-filler-autocomplete-question-view.png new file mode 100644 index 000000000..58f98a264 Binary files /dev/null and b/design/features/add-answer-for-none-of-the-above/Screenshots/009-form-filler-autocomplete-question-view.png differ diff --git a/design/features/add-answer-for-none-of-the-above/Screenshots/010-form-filler-check-your-answers-page.png b/design/features/add-answer-for-none-of-the-above/Screenshots/010-form-filler-check-your-answers-page.png new file mode 100644 index 000000000..35f5438b8 Binary files /dev/null and b/design/features/add-answer-for-none-of-the-above/Screenshots/010-form-filler-check-your-answers-page.png differ diff --git a/design/features/add-answer-for-none-of-the-above/Screenshots/README.md b/design/features/add-answer-for-none-of-the-above/Screenshots/README.md new file mode 100644 index 000000000..e8b49d504 --- /dev/null +++ b/design/features/add-answer-for-none-of-the-above/Screenshots/README.md @@ -0,0 +1 @@ +This folder contains screenshots for the feature that lets people add another answer if they've selected 'none of the above' for a selection question diff --git a/design/features/add-answer-for-none-of-the-above/version-1.md b/design/features/add-answer-for-none-of-the-above/version-1.md new file mode 100644 index 000000000..26242e3cb --- /dev/null +++ b/design/features/add-answer-for-none-of-the-above/version-1.md @@ -0,0 +1,351 @@ +# Let people add an answer if ‘none of the above’ is selected + +## Status +- Date released: 16 January 2026 +- [Epic Trello card](https://trello.com/c/4G5NLRvN) +- [Let people add an answer if ‘none of the above’ is selected feature document](https://docs.google.com/document/d/1Urs-5dWqS5GVL283OfxaA7mPcAHpMpSa2UbLLIWO5hg/edit?pli=1&tab=t.0) +- [Mural board](https://app.mural.co/t/gaap0347/m/gaap0347/1760012750571/b19691c8f6154638b5782f172d311831a63a7af4) + +## Contents + +- [What is this feature?](#what-is-this-feature) +- [Key decisions](#key-decisions) +- [Designs and content](#designs-and-content) + +## What is this feature? +We allow users to select ‘None of the above’ when selecting from a list of options, but we don’t provide a way for them to specify what their answer would be. +We should let users describe what their ‘none of the above’ item would be, if form creators want to allow this. + +### As-is +Form creators can add a ‘None of the above’ option to a list question. + +Form fillers can select this option, but they do not currently have a way to add what their ‘none of the above’ answer would be. + +### To-be +Form creators will be able to choose whether or not to let form fillers add an answer if they’ve selected ‘none of the above’ from a selection-list question. They’ll also be able to make adding an answer optional for form fillers. + +## Key decisions + +### Scope + +It was agreed that the following was in scope: + +- Allow a none-of-the-above option with additional information on both radio and checkbox options +- Allow form fillers to give additional information to a question where their answer does not fit the options provided +- Offer a single-line text input for a form fillers’ answer +- Form creators will add a label or question content for the text input +- Long list of options (for form filler) - with select/autocomplete component +- Make ‘none of the above’ information optional - we originally intended to make it mandatory as this was simpler, but the designs we decided on allowed us to include this choice + +The following was agreed to be out of scope: + +- Allow form creators to choose the answer type they want form fillers to give if selecting ‘none of the above’ +- Allow form creators to ask for more than 1 answer type when none-of-the-above is selected +- Offer a multi-line text area for form filler’s answer +- Allow form creators to decide what the content for the none-of-the-above option is (for example, ‘Other’) + +### Design decisions + +- We’ll let form creators choose if they want to allow people to give a different answer if they select ‘none of the above’ to a selection question. +- We’ll add a new radio option when form creators answer the question ‘Should the list include an option for ‘None of the above’?’. As well as ‘Yes’ and ‘No’ options, form creators will be able to choose ‘Yes, and let people provide a different answer’. +- If this new option is selected, we’ll show form fillers a text box to enter their answer when they select ‘None of the above’. We’ll need to ask form creators for a question or label for this new input field. +- We’ll let form creators select whether an answer to this ‘additional’ question is mandatory or not. +- We’ll use the standard form-filler error messages for radios, checkboxes and single lines of text. +- When the initial question has a long list of options (and uses the select/autocomplete component), we'll add a second page for the additional 'none of the above' question - we checked that this would be possible without interfering with routing +- Even if someone selects ‘none of the above’ and types an answer in exactly the same way as one of the options in the original list, it should still be treated as a ‘none of the above’ answer for the purposes of routing. +- We need to consider related changes in form submissions and in the details page for live or archived forms. + +### ‘Other’ v ‘none of the above’ +We briefly talked about whether we should change ‘none of the above’ to ‘other’, or allow people to change the wording themselves. We’ve had some people ask about this in feedback and Zendesk requests. + +It was noted that ‘other’ implies that there IS a different answer, whereas ‘none of the above’ does not suggest this as much. + +While it was agreed that ‘other’ might feel more appropriate than 'none of the above' if someone is able to add another answer, ‘none of the above’ works for both instances - where there is another answer AND where there is not. We think this is probably why we used ‘None of the above’ for list questions initially. + +So while we’re not allowing people to select or change how it’s worded, we agreed to stick with ‘None of the above’ and leave any changes for a future iteration. + +## Designs and content + +### Summary of new designs and content + +When a form creator creates a ‘Selection from a list of options’ question, they add their question text, select ‘one option only’ or ‘one or more options’, and are then taken to a ‘Create a list of options’ page. + +On this page, there’s an ‘Add options to your list’ legend, followed by text boxes where form creators can add the relevant answer options to their list. + +This is followed by an H2 heading that reads ‘Should the list include an option for none of the above?’. + +Previously, a form creator had only 2 radio button options to choose from - ‘Yes’ and ‘No’. Under ‘Yes’ the hint text said ‘If you select ‘Yes’ we’ll add ‘None of the above’ to the end of your list of options’. + +This new feature adds a third radio option with the label ‘Yes, and let people provide a different answer’. This sits between the ‘Yes’ and ‘No’ radio options. + +The hint text has been moved from the ‘Yes’ radio option to under the H2 heading ‘Should the list include an option for ‘None of the above’?’. This is because there are now 2 ‘Yes’ options to choose from and it makes more sense to have the hint text at the top as it applies to both. + +We've made the same changes to the equivalent question on the 'Enter your list’s options into a text box' page - which people can chose to use rather than entering the options individually. + +We’ve added a new page that form creators will see if they choose to ask someone for an answer if they select ‘none of the above’. On this page, they’re asked to enter a question or label for the text box that form fillers will see. We provide hint text to help them do this more effectively. + +Form creators can also select whether entering an answer for this ‘additional question’ should be mandatory or optional. + +The designs and content that were edited or created for this feature are: + +- ‘Create a list of options’ page (iteration) +- ‘Enter your list’s options into a text box’ page (iteration) +- ‘Ask for an answer if someone selects ‘None of the above’’ page (new) +- ‘Edit question’ page (iteration) +- Live and archived forms’ questions page (iteration) +- Submission email (iteration) +- CSV file (iteration) +- JSON file (iteration) +- Question X, for radio and checkboxes - form filler additional question view (iteration) +- Question X, autocomplete - form filler view (iteration) +- Question Xa, autocomplete - form filler view (new) +- ‘Check your answers’ page - form filler view (iteration) + + +### ‘Create a list of options’ page - new radio option + +screenshot is described in the following content + +**Description of the image and changes made:** + +This screenshot shows the H1 page heading ‘Create a list of options’. This is the third page form creators will see when creating a ‘Selection from a list of options’ question - after ‘What’s your question?’ and ‘How many options should people be able to select?’. + +The H1 is followed by content explaining how many options form fillers can select from the list and how they can do this. + +Below that, form fillers can add options to their list in the usual way, adding more text boxes as needed. + +There’s then an H2 that reads: + +> Should the list include an option for ‘None of the above’? + +This is followed by hint text that says: + + > If you select ‘Yes’ we’ll add ‘None of the above’ to the end of your list of options. + +This is followed by 3 radio options, the second of which is new: + +> - Yes +> - Yes, and let people provide a different answer +> - No + +The new radio option, which says ‘Yes, and let people provide a different answer’, lets form creators ask someone for an answer if they select ‘none of the above’. + +If form creators select this option, they’ll be taken to the ‘Ask for an answer if someone selects ‘None of the above’’ page. + +If they select the ‘Yes’ or ‘No’ radio options instead, they’ll be taken straight to the ‘Edit question’ page, as usual. + +The new ‘none of the above’ radio option also appears on the page that form creators see if they choose to enter all the options into one text box. + + +### ‘Ask for an answer if someone selects ‘None of the above’’ - new page + +screenshot is described in the following content + +**Description of the image:** + +This screenshot shows the new page that lets form creators enter a question or label for the text box form fillers will see if they select ‘none of the above’. + +The H1 heading reads: + +> Ask for an answer if someone selects ‘None of the above’ + +Below this is some text that says: + +> If someone selects ‘None of the above’, we’ll show them a text box to enter their answer. + +That’s followed by a label that reads: + +> ‘Enter a question or label for the text box’ + +The hint text beneath this is: + +> For example, if you asked them to select the country they live in, you could use ‘Enter the country you live in’. + +Beneath the text box where form creators can add their label or question is an H2 heading that reads: + +> Should this additional question be mandatory or optional? + +We added the word ‘additional’ here to help form creators understand that we’re not referring to the main question. + +As usual, the 2 radio buttons are labelled ‘Mandatory’ and ‘Optional’, and the hint text under ‘Optional’ says that we’ll add ‘Optional’ to the end of the question or label. + + +### ‘Edit question’ page - new row under ‘Answer settings’ + +screenshot is described in the following content + +This screenshot shows the page that form creators see once they’ve added options to their select-from-a-list question. + +The page’s H1 is ‘Edit question’. This is followed by the usual ‘Question text’ and ‘Hint text (optional)’ text boxes and the H2 heading ‘Guidance’. + +Beneath this is the usual H2 ‘Answer settings’ with a summary list showing 5 rows. Each row is divided by a grey horizontal line. + +The 5 row headings are: + +> Answer type +> Options +> How many options can people select +> Include an option for ‘none of the above’ +> If ‘none of the above’ is selected + +The first 4 are the same as usual, but the fifth is new - ‘If ‘none of the above’ is selected’. Next to this is whatever value (or text) the form creator has added as the additional question or label. + +Beneath the summary list is the usual green ‘Save question’ button and a ‘Back to your questions’ link. + + +### Live form’s ‘Your questions’ page + +screenshot is described in the following content + +**Description of the image and changes made:** + +This screenshot shows the top part of a live ‘Your questions’ page. This is the page form creators see if they’ve made their form live and are viewing that form’s questions. (It also appears in this way on an archived form’s equivalent page.) + +Under the H1 ‘Your questions’ are 2 summary cards, showing the form’s first 2 questions - these are both selection-from-a-list questions. + +Question 1’s summary card displays the question text in the usual way - bold text on a grey background in the first row. It has 2 more rows with bold row headers saying ‘Answer type’ and ‘Options’. + +Question 2’s summary card follows this same pattern, but it has an extra row which shows the new ‘none of the above’ additional answer option. + +The summary card title, in bold text on a grey background, reads: + +> ‘2. What’s your favourite colour?’ + +This is followed by 3 rows, which read: + +> Answer type: Selection from a list, one option only +> Options: Show 37 options [this is a clickable details component] +> If ‘none of the above’ is selected: Enter your favourite colour (optional) + +The last row, with the row header ‘If ‘none of the above’ is selected’, is new. It shows whatever label text the form creator has chosen to add, and states if this is optional. + +We considered an alternative design for displaying this information. This added a separate ‘None of the above’ heading and section to the summary card. It had row headers - ‘Input label’, followed by the form creator’s question text or label, and ‘Is the input optional?’, followed by ‘Yes’ or ‘No’. We decided against this design as it was less concise, used less plain English and made the summary card for that answer significantly longer. + + +### Showing ‘none of the above’ answer in a submission email + +screenshot is described in the following content + +**Description of the image and changes made:** + +This screenshot shows a snippet of a Mural design for how a form filler’s additional ‘none of the above’ answer will appear in the submission email that form processors receive. + +There are 4 questions shown, each divided by a horizontal grey line. + +The second question is the relevant one for this feature. It shows a select-from-a-list question where someone has selected ‘None of the above’ and entered an additional answer. + +The H3 question text reads: + +> What’s your favourite colour for juggling balls? + +The answer below is ‘None of the above’. + +Beneath this is the additional question or label text the form creator has added. This is an H4 and reads: + +> Enter your favourite colour + +The answer below is ‘Midnight blue’. + +There are 2 yellow post-it notes which show some discussion about this design decision. One is querying the use of an H4 heading but it was agreed that, although we may avoid using H4s for the web, it was fine in this instance. + +The other post-it specifies what should happen if the form creator makes the additional question optional. This reads: + +> If it's an optional follow-up question that the form filler doesn't answer, this will say [This question was skipped] as we do for other optional questions. + + +### Showing ‘none of the above’ answer in CSV file + +screenshot is described in the following content + +**Description of the image and changes made:** + +This screenshot shows how a form filler’s additional ‘none of the above’ answer will appear in a CSV file - if form creators have chosen to receive a CSV for a submitted form. + +The CSV stores data in a tabular format similar to a spreadsheet and, in this screenshot, has 2 rows and 5 columns (A to E). + +The CSV data follows the usual format, with cell 1A showing the column header ‘Reference’ and cell 2A showing the reference number for this form. Cell 1B shows the header ‘Submitted at’ and cell 2b shows the time and date of submission. + +The following columns all have the question text in row 1, and the answer to that question in the cell below (row 2). + +What’s new is that a form filler’s additional answer is shown in the same cell as the ‘None of the above’ response, separated by a hyphen. + +In this instance, the answer to column D’s question - ‘What’s your favourite juggling-balls colour?’ reads: + +> None of the above - Emerald + +If the additional question is optional and not answered, we agreed to show the text: + +> ‘None of the above -’ + +We decided against having an extra column for the additional question’s text and answer, although there was discussion about this. There were concerns about whether form processors might want to separate the 2, and whether separating them with a hyphen within the same cell was enough. The overall consensus was that it’s more obvious that the additional answer is related to the ‘none of the above’ question if it’s in the same cell. This was considered important as the person processing the form might not be the person who created it. It also means the processor does not have to check whether one column has ‘None of the above’ before looking in another column for the related answer. + + +### Showing ‘none of the above’ answer in JSON file + +screenshot is described in the following content + +**Description of the image and changes made:** + +This screenshot shows a snippet from a JSON file that illustrates how the additional ‘none of the above’ answer is shown in code for this sort of question. + +Each line of code has keys named in the usual way - “question_id”, “question_text”, “answer_text”, etc. This is followed by the related value for that key. + +What’s different here is that, as well as the key “selection” and the value “None of the above” - which is usual for a selection question - there’s an extra line of code which reads: + +> “none_of_the_above_answer”: “Emerald” + +Below this is the usual “answer_text” key. But instead of the value being “None of the above”, it includes the additional answer to the question, separated by a hyphen: + +> “None of the above - Emerald” + +This is consistent with how this data is presented in the CSV. + +The decision to present it in this way was based on advice from developers that we usually need feedback from real JSON users to know what works best. We plan to consider such feedback in the future. + + +### Form filler view of the feature + +screenshot is described in the following content + +**Description of the image and changes made:** + +This screenshot shows what someone answering a select-from-a-list question with the option ‘None of the above’ will see if the form creator has chosen to let them add an additional answer. + +The question here is “What’s your favourite colour”? This is followed by 2 radio options labelled “Red” and “Blue”. Below these is a grey text divider saying ‘“or” and a further radio button labelled “None of the above”. + +What’s new is that if someone selects “None of the above”, they’ll see a conditional reveal of the related question, as in this screenshot. It displays as a vertical grey line to the left of a text box with the input label above it. + +The input label here reads: + +> Enter your favourite colour (optional) + +Below is the green ‘Continue’ button. + +The same pattern is used for checkboxes, but it changes slightly if the question uses select and autocomplete - as below. + +screenshot is described in the following content + +**Description of the image and changes made:** + +This screenshot shows the new screen a form filler will see if they’ve chosen ‘None of the above’ from a long list of options using the autocomplete function. + +Instead of a conditional reveal on the same page, they’ll be taken to this new page. + +It shows the label “Enter your favourite colour (optional)” above a text box input for their answer. This is followed by the green ‘Continue’ button. + + +### ‘Check your answers’ page - with additional ‘none of the above’ question + +screenshot is described in the following content + +This screenshot shows the usual ‘Check your answers before submitting your form’ page. + +Beneath the heading are 4 rows. Each row header is in bold, followed by the answer and a ‘Change’ link at the far right end of each row. + +As usual, the selection question - which in this example is “What’s your favourite colour?” - appears as the row header. This is followed by the answer text “None of the above”, and a ‘Change’ link at the end of the row. + +What’s new is the row immediately below this, which shows the additional ‘none of the above’ question. The row header for this reads: + +> Enter your favourite colour (optional) + +It’s followed by the answer ‘Emerald’ and the ‘Change’ link at the end of the row. diff --git a/design/features/getting-completed-form-submissions/README.md b/design/features/getting-completed-form-submissions/README.md index 51777d35b..0d6f51ead 100644 --- a/design/features/getting-completed-form-submissions/README.md +++ b/design/features/getting-completed-form-submissions/README.md @@ -42,8 +42,10 @@ We need to make several changes to the task list to properly represent the S3 op So in January 2026, we added a details component to the page where form creators set the email address for completed forms. This tells them S3 buckets is an option, and links to the [processing completed form submissions](https://www.forms.service.gov.uk/processing-completed-form-submissions) guidance on the product site which has more information and tells them to contact us to set it up. +### [Daily batches of form submissions in CSV](version-4-daily-batch-submissions.md) +Added an option to be sent a daily email with a CSV of data from all submissions to a form from the previous day. +### [Weekly batches of form submissions in CSV](version-5-weekly-batch-submissions.md) - - +Added an option to be sent a weekly email with a CSV of data from all submissions to a form from the previous week. diff --git a/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions-screenshots/001-change-how-you-get-completed-forms.png b/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions-screenshots/001-change-how-you-get-completed-forms.png new file mode 100644 index 000000000..681d7bea1 Binary files /dev/null and b/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions-screenshots/001-change-how-you-get-completed-forms.png differ diff --git a/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions-screenshots/002-get-a-daily-CSV-of-the-previous-days-completed-forms.png b/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions-screenshots/002-get-a-daily-CSV-of-the-previous-days-completed-forms.png new file mode 100644 index 000000000..caa361c49 Binary files /dev/null and b/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions-screenshots/002-get-a-daily-CSV-of-the-previous-days-completed-forms.png differ diff --git a/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions-screenshots/003-how-you-get-completed-forms-live.png b/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions-screenshots/003-how-you-get-completed-forms-live.png new file mode 100644 index 000000000..bc3cad06c Binary files /dev/null and b/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions-screenshots/003-how-you-get-completed-forms-live.png differ diff --git a/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions-screenshots/1001-daily-submission-email-live-fixed.png b/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions-screenshots/1001-daily-submission-email-live-fixed.png new file mode 100644 index 000000000..24e957320 Binary files /dev/null and b/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions-screenshots/1001-daily-submission-email-live-fixed.png differ diff --git a/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions-screenshots/1002-daily-submission-email-preview.png b/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions-screenshots/1002-daily-submission-email-preview.png new file mode 100644 index 000000000..30b5eeb57 Binary files /dev/null and b/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions-screenshots/1002-daily-submission-email-preview.png differ diff --git a/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions-screenshots/README.md b/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions-screenshots/README.md new file mode 100644 index 000000000..07cda507a --- /dev/null +++ b/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions-screenshots/README.md @@ -0,0 +1 @@ +This folder contians screenshots of the work done for collated CSV submission emails. diff --git a/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions.md b/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions.md new file mode 100644 index 000000000..95b5c2a9d --- /dev/null +++ b/design/features/getting-completed-form-submissions/version-4-daily-batch-submissions.md @@ -0,0 +1,161 @@ + # Daily batch of submissions + +- Date released: March 2026 +- [Epic Trello card](https://trello.com/c/KsrXbLgd/156-collating-submissions-into-one-file?search_id=3eb9774f-544c-443c-b460-b717ba991c23) +- [Mural board](https://app.mural.co/t/gaap0347/m/gaap0347/1770127108440/d7a891c1cc0123b6ccbb35e593bb7b00ce38d083?wid=0-1770202192308) +- [Content document](https://docs.google.com/document/d/1aHnUZ6RWI2aj9yi-MciAy-NexJzWtynNV2NEGZyioAc/edit?usp=sharing) +___ + +## Contents + +- [What is this iteration](#what-is-this-iteration) +- [Design and content](#design-and-content) + +___ + +## What is this iteration? + +This added the option for form owners to get a daily email with an attached CSV file containg all submissions to a single form from the previous day. This email will not contain any uploaded files and so will be alongside existing inidividual submissions. + +### As-is + +Form creators get answers from each completed form sent to them by email or through an S3 bucket (which is less common). + +### To-be + +People can also opt to receive a collated CSV file of all the submissions to a form from the previous day. + +### Why? + +We believe providing a daily collation of submissions will help some users of the form data get a better idea of how forms are working and what might be causing issues with people completing their forms. It can also be used to get a better understanding of the contact types allowing future iteration or simplification. + +We also know many of our users currently copy and paste individual submission data into a single spreadsheet file. We believe providing this daily file of submissions may help to make this process more efficient for them. + +## Design and content + +The designs and content changed for this iteration were: + +### Task list + +Task list section for “Change how you get completed forms”. Screenshot + +As part of the work to include the new collated CSV as an option for form creators to select, we added a new optional task to section 2 of the task list. Section 2 is called “Set up how you get completed forms” when creating a form or “Change how you get completed forms” when editing a form. + +The section still shows the link to edit the email address completed forms are sent to with the previously set email that submissions are currently sent to beneath. Then the task to enter the confirmation code we sent to the email to confirm they had access. It reads: + +> 2\. Change how you get completed forms +> +> Edit the email address compelted forms will be sent to (link) : Completed +> Completed forms will be sent to: example@department.gov.uk +> +> Enter the email address confirmation code (unlinked) : Completed + +Under the original tasks is the existing ‘optional task’ to “Get a CSV or JSON file of each completed form” which has not been selected so remains with the status tag ‘optional’ alongside. + +Next is the new optional task added: + +> Get a daily CSV of the previous day’s completed forms : Optional + +Since we've added a second optional task, we also updated the subsection heading from ‘Optional task’ to ‘Optional tasks’. + + +### Get a daily CSV of the previous day’s completed forms + +Get a daily CSV of the previous day’s completed forms page. Screenshot + +This is the newly added task screen providing information about the feature and what it does and does not offer, with the option for the form creator to pick if they want to get the collated files. The page reads: + +> H1: Get a daily CSV of the previous day’s completed forms +> +> You can get a daily email with all the answers from the previous day’s completed forms collected into a CSV file. +> +> The CSV will list all the answers in plain text, separated by commas, with a row for each completed form. +> +> We’ll send the email shortly after 2am with the completed forms from the previous day. It’ll be sent to the same email address you set for completed forms. +> +> If you make changes to the form such as adding, moving or deleting a question, the structure of the CSV will change. Forms completed before and after the change will be split into separate CSV files. +> +> You’ll continue to receive individual completed form emails. If your form has any file upload questions, the uploaded files will only be attached to the individual completed form emails. + +Finally the page ends with the question “Do you want to get a daily CSV of the previous day’s completed forms?” and a single checkbox for the form creator to select or deselect: + +> Get a daily CSV of completed forms + + +### How you get completed forms - read-only view + +Viewing a live form how you get completed forms section. Screenshot + +As part of this release we are showing a new subsection on the live form read-only page as part of the “How you get completed forms” section. Beneath the set email and whether they have chosen to receive a CSV or JSON as part of the individual email submissions, we have a new “Daily CSV” heading. It informs the person looking at this page whether the form is also set up to receive a daily CSV of all previous day’s submissions. The screenshot shows: + +> H3: How you get completed forms +> +> H4: Email +> example@department.gov.uk +> +> H4: CSV and JSON +> You have not opted to also get each completed form as a JSON or CSV file. +> +> H4: Daily CSV +> You have not opted to get a daily CSV of the previous day’s completed forms. + +The last line would change to read “You are getting a daily CSV of the previous day’s completed forms.” if the form creator has decided they want a daily CSV file. + + +### Daily collation email - live form version + +Daily form submissions, live form example email. Screenshot + +This is an example of the new daily email that will be sent to the processing email address. + +- The email will be sent just after 2am each day and contain all submissions from the previous day collated into a single CSV file. +- The CSV will not include uploaded files from the form but will include the associated filename for the form processors to be able to link the submission and file. + +The email subject line for live forms reads: + +> Daily form submissions: ‘[Form name]’ - xx month year + +The email reads: + +> Form name: “[form name]” +> +> All submissions to this form from xx month year are attached to this email in [a CSV file named | CSV files named]: +> - govuk_forms_form_name_2026-02-13_1 +> - govuk_forms_form_name_2026-02-13_2 +> - govuk_forms_form_name_2026-02-13_3 +> +> > Check that these answers look safe before you use them +> +> Submissions are split into separate CSV files if the form’s been changed in a way that affects the structure of the CSV. +> +> For forms with file upload questions, the uploaded files will only be attached to the individual completed form emails. +> +> > **You cannot reply to this email** +> > +> > If you’re experiencing a technical issue with this form, contact the GOV.UK Forms team (linked) with details of the issues and the form it relates to. + +### Daily collation email - preview version + +Test daily form submissions, draft form example email. Screenshot + +This is an example of the collated email where someone is previewing a form and submits it. It is mostly the same as the live version with a couple of exceptions. + +The email subject line reads: + +> TEST DAILY FORM SUBMISSIONS: [Form name] - xx month year + +Using “TEST” and capitalisation to distinguish quickly between the live data and preview data, and allow form processors to set up mailbox forwarding and filtering if they need to. + +We have also included an additional line at the start of the email body: + +> These are test submissions to a preview of [a draft | a live | an archived] form. + +We have also added “test_” to the start of each attached CSV filename to help distinguish between live data and test, or preview data in case there is automation happening and in case they download these files. + +
+ +___ + +
+ +[Back to the top](#daily-batch-of-submissions) diff --git a/design/features/getting-completed-form-submissions/version-5-weekly-batch-submissions-screenshots/001-task-list-weekly-csv-task.png b/design/features/getting-completed-form-submissions/version-5-weekly-batch-submissions-screenshots/001-task-list-weekly-csv-task.png new file mode 100644 index 000000000..3649a3486 Binary files /dev/null and b/design/features/getting-completed-form-submissions/version-5-weekly-batch-submissions-screenshots/001-task-list-weekly-csv-task.png differ diff --git a/design/features/getting-completed-form-submissions/version-5-weekly-batch-submissions-screenshots/002-Get-a-daily-or-weekly-batch-of-completed-forms.png b/design/features/getting-completed-form-submissions/version-5-weekly-batch-submissions-screenshots/002-Get-a-daily-or-weekly-batch-of-completed-forms.png new file mode 100644 index 000000000..a7860143e Binary files /dev/null and b/design/features/getting-completed-form-submissions/version-5-weekly-batch-submissions-screenshots/002-Get-a-daily-or-weekly-batch-of-completed-forms.png differ diff --git a/design/features/getting-completed-form-submissions/version-5-weekly-batch-submissions-screenshots/README.md b/design/features/getting-completed-form-submissions/version-5-weekly-batch-submissions-screenshots/README.md new file mode 100644 index 000000000..b064be29e --- /dev/null +++ b/design/features/getting-completed-form-submissions/version-5-weekly-batch-submissions-screenshots/README.md @@ -0,0 +1 @@ +This folder contains screenshots for the weekly form submission CSVs feature. diff --git a/design/features/getting-completed-form-submissions/version-5-weekly-batch-submissions.md b/design/features/getting-completed-form-submissions/version-5-weekly-batch-submissions.md new file mode 100644 index 000000000..baa385385 --- /dev/null +++ b/design/features/getting-completed-form-submissions/version-5-weekly-batch-submissions.md @@ -0,0 +1,166 @@ +# Weekly batch of submissions + +- Date released: 30 March 2026 +- [Epic Trello card](https://trello.com/c/KsrXbLgd/156-collating-submissions-into-one-file) +- [Daily and weekly collated submissions CSV - Mural](https://app.mural.co/t/gaap0347/m/gaap0347/1770127108440/d7a891c1cc0123b6ccbb35e593bb7b00ce38d083?sender=u12d19b597a88e8b64fc22126) +- [Daily and weekly CSV of form submissions - content notes](https://docs.google.com/document/d/1aHnUZ6RWI2aj9yi-MciAy-NexJzWtynNV2NEGZyioAc/edit?pli=1&tab=t.udaypy8b13up#heading=h.6iwzmd16d9b8) +--- + +## Contents + +- [What is this iteration](#what-is-this-iteration) +- [Design and content](#design-and-content) + +--- +## What is this iteration? + +This added the option for form owners to get a weekly email with an attached CSV file containing all submissions to a single form from the previous week. The email does not contain any uploaded files for file upload questions, so individual submissions continue as normal. + +### As-is + +Form creators get answers from each completed form sent to them by email or through an S3 bucket (which is less common). They can also get a daily batch of submissions to a form as a CSV file attached to an email. + +### To-be + +People can also opt to receive a weekly batch of submissions in a CSV file, with all the submissions to a form from the previous week. The CSV is sent on a Monday morning to the email address that is set for completed forms. + +### Why? + +We know many of our users currently collect individual submission data into a single spreadsheet file for various reasons - such as for processing, record keeping and analysing response data in bulk. + +We provided daily batches as a first iteration to help people to do this more easily. We are expanding this to a weekly batch to, hopefully, make further efficiency improvements. + +--- +## Design and content + +The designs and content changed for this iteration were: + +### Task list +screenshot is described in the following content + +In section 2 of the task list, pictured above, we changed the name of the existing optional weekly batch task from: + +> Get a daily CSV of the previous day’s completed forms + +To: + +> Get a daily or weekly batch of completed forms + +This introduced the terminology of ‘batches’ for the first time. This was needed to avoid having to say “all of the completed forms from the previous day or week”. + +### Task page: Get a daily or weekly batch of completed forms + +The task page has a new heading and content - including an additional checkbox - to explain the options of daily and weekly batches of form submissions, and allow the form creator to select if they want either of them. + +screenshot is described in the following content + +The new H1 heading is: + +> Get a daily or weekly batch of completed forms + +Then there is some guidance: + +> You can get a daily or weekly CSV file of all the submissions to this form from the previous day or week. +> +> The CSVs will be sent: +> - to the email address you’ve set for completed forms +> - shortly after 2am each day for a daily CSV +> - shortly after 2am on Monday mornings for a weekly CSV +> +> The CSVs will include each submission’s answers in plain text separated by commas - plus the date and time of submission. +> +> If you make changes to the form such as adding, moving or deleting a question, the structure of the CSV will change. Forms completed before and after the change will be split into separate CSV files. +> +> You’ll continue to receive individual completed form submissions in the usual way. If your form has any file upload questions, the uploaded files will only be attached to the individual submissions. + +Then a question: + +> Do you want to get a daily or weekly CSV of submissions to this form? + +Followed by 2 checkbox options: + +> - Get a daily CSV of submissions +> - Get a weekly CSV of submissions + +Then a green ‘Save and continue’ button. + +#### Success banner notifications + +If the form creator changes the current settings on the task page and saves them, they are returned to the task list page and the relevant success banner will be displayed. There are 4 versions: + +- You’ll get a daily batch of form submissions +- You’ll get a weekly batch of form submissions +- You’ll get daily and weekly batches of form submissions +- You will not get a daily or weekly batch of form submissions + +If the form creator makes no changes, no success banner is displayed when they return to the task list page. + +### Live and archived form’s details page + +On the live or archived form’s read-only details page we display the form’s current settings for daily and weekly batches. + +In the “How you get completed forms” section, we show an H3: + +> Daily and weekly CSVs + +Beneath this, we show the relevant line of the 4 possibilities: +- You are getting a daily batch of completed forms. +- You are getting a weekly batch of completed forms. +- You are getting daily and weekly batches of completed forms. +- You have not opted to get a daily or weekly batch of completed forms. + +### Weekly batch emails + +The weekly batch email will: +- be sent on Mondays shortly after 2am at a similar time to the daily batch emails +- include CSVs for the previous week’s submission to the form +- not include any file uploads from file upload questions - these will only be sent with the individual submissions + +We’ve adapted the daily batch email template for weekly batches. + +The subject for the email is: + +> Weekly form submissions: ‘[Form name]’ - xx month year to xx month year + +The body content is: + +> Form name: “[form name]” +> +> All submissions to this form from xx month year to xx month year are attached to this email in [a CSV file named | CSV files named]: +> - govuk_forms_form_name_2026-02-13--2026-02-19_1 +> - govuk_forms_form_name_2026-02-13--2026-02-19_2 +> - govuk_forms_form_name_2026-02-13--2026-02-19_3 +> +> > Check that these answers look safe before you use them +> +> Submissions are split into separate CSV files if the form’s been changed in a way that affects the structure of the CSV. +> +> For forms with file upload questions, the uploaded files will only be attached to the individual completed form submissions. +> +> > **You cannot reply to this email** +> > +> > If you’re experiencing a technical issue with this form, contact the GOV.UK Forms team (linked) with details of the issue and the form it relates to. + +#### Preview version of the email + +Any submission to a preview of the form will be sent in a separate CSV in a separate email. They’ll be clearly marked as test submissions. This allows people to test this functionality, without getting them confused as real submissions. + +The email template is largely the same with the following difference. + +The email subject line reads: + +> TEST WEEKLY FORM SUBMISSIONS: [Form name] - xx month year to xx month year + +We include a line at the start of the body of the email to say: + +> These are test submissions to a preview of [a draft | a live | an archived] form. + +We have also added “test_” to the start of each attached CSV filename to differentiate these files even if they are downloaded to a user’s computer. + +
+ +___ + +
+ +[Back to the top](#weekly-batch-of-submissions) diff --git a/design/features/welsh-version/README.md b/design/features/welsh-version/README.md index 29ce2965b..a8d9828a8 100644 --- a/design/features/welsh-version/README.md +++ b/design/features/welsh-version/README.md @@ -2,7 +2,7 @@ ## Status -Current version: 1 +Current version: 2 - iteration based on research Date created: 17 November 2025 ___ diff --git a/design/features/welsh-version/screenshots-v2/001-create-a-form-new-form.png b/design/features/welsh-version/screenshots-v2/001-create-a-form-new-form.png new file mode 100644 index 000000000..692a56b0d Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/001-create-a-form-new-form.png differ diff --git a/design/features/welsh-version/screenshots-v2/002-add-a-welsh-version-new-form.png b/design/features/welsh-version/screenshots-v2/002-add-a-welsh-version-new-form.png new file mode 100644 index 000000000..4ce33884b Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/002-add-a-welsh-version-new-form.png differ diff --git a/design/features/welsh-version/screenshots-v2/003-create-a-form-created-welsh-version-without-any-content.png b/design/features/welsh-version/screenshots-v2/003-create-a-form-created-welsh-version-without-any-content.png new file mode 100644 index 000000000..cedc91cb4 Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/003-create-a-form-created-welsh-version-without-any-content.png differ diff --git a/design/features/welsh-version/screenshots-v2/004-add-a-welsh-version-saved-welsh-version.png b/design/features/welsh-version/screenshots-v2/004-add-a-welsh-version-saved-welsh-version.png new file mode 100644 index 000000000..82c5f24ec Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/004-add-a-welsh-version-saved-welsh-version.png differ diff --git a/design/features/welsh-version/screenshots-v2/005-delete-welsh-version.png b/design/features/welsh-version/screenshots-v2/005-delete-welsh-version.png new file mode 100644 index 000000000..35c357b44 Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/005-delete-welsh-version.png differ diff --git a/design/features/welsh-version/screenshots-v2/006-create-a-form-deleted-welsh-version.png b/design/features/welsh-version/screenshots-v2/006-create-a-form-deleted-welsh-version.png new file mode 100644 index 000000000..7c18daf18 Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/006-create-a-form-deleted-welsh-version.png differ diff --git a/design/features/welsh-version/screenshots-v2/007-add-a-welsh-version-added-questions.png b/design/features/welsh-version/screenshots-v2/007-add-a-welsh-version-added-questions.png new file mode 100644 index 000000000..2b3c286b5 Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/007-add-a-welsh-version-added-questions.png differ diff --git a/design/features/welsh-version/screenshots-v2/008-previewing-new-form-without-questions.png b/design/features/welsh-version/screenshots-v2/008-previewing-new-form-without-questions.png new file mode 100644 index 000000000..0e3834f55 Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/008-previewing-new-form-without-questions.png differ diff --git a/design/features/welsh-version/screenshots-v2/009-previewing-form-without-welsh-translations-but-welsh-version-english.png b/design/features/welsh-version/screenshots-v2/009-previewing-form-without-welsh-translations-but-welsh-version-english.png new file mode 100644 index 000000000..4b3961ec3 Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/009-previewing-form-without-welsh-translations-but-welsh-version-english.png differ diff --git a/design/features/welsh-version/screenshots-v2/009-previewing-form-without-welsh-translations-but-welsh-version-welsh.png b/design/features/welsh-version/screenshots-v2/009-previewing-form-without-welsh-translations-but-welsh-version-welsh.png new file mode 100644 index 000000000..c1997a16b Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/009-previewing-form-without-welsh-translations-but-welsh-version-welsh.png differ diff --git a/design/features/welsh-version/screenshots-v2/011-add-a-welsh-version-complete-form.png b/design/features/welsh-version/screenshots-v2/011-add-a-welsh-version-complete-form.png new file mode 100644 index 000000000..00cce3712 Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/011-add-a-welsh-version-complete-form.png differ diff --git a/design/features/welsh-version/screenshots-v2/011-add-a-welsh-version-complete-translations.png b/design/features/welsh-version/screenshots-v2/011-add-a-welsh-version-complete-translations.png new file mode 100644 index 000000000..f158a8c2e Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/011-add-a-welsh-version-complete-translations.png differ diff --git a/design/features/welsh-version/screenshots-v2/012-create-a-form-complete-form.png b/design/features/welsh-version/screenshots-v2/012-create-a-form-complete-form.png new file mode 100644 index 000000000..f641d4bd5 Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/012-create-a-form-complete-form.png differ diff --git a/design/features/welsh-version/screenshots-v2/012-create-a-form-complete-welsh.png b/design/features/welsh-version/screenshots-v2/012-create-a-form-complete-welsh.png new file mode 100644 index 000000000..3465f7b76 Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/012-create-a-form-complete-welsh.png differ diff --git a/design/features/welsh-version/screenshots-v2/013-make-form-live.png b/design/features/welsh-version/screenshots-v2/013-make-form-live.png new file mode 100644 index 000000000..74eba23a2 Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/013-make-form-live.png differ diff --git a/design/features/welsh-version/screenshots-v2/014-form-live.png b/design/features/welsh-version/screenshots-v2/014-form-live.png new file mode 100644 index 000000000..f919f40fc Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/014-form-live.png differ diff --git a/design/features/welsh-version/screenshots-v2/015-live-form-readonly.png b/design/features/welsh-version/screenshots-v2/015-live-form-readonly.png new file mode 100644 index 000000000..431b44435 Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/015-live-form-readonly.png differ diff --git a/design/features/welsh-version/screenshots-v2/016-live-form-questions-readonly.png b/design/features/welsh-version/screenshots-v2/016-live-form-questions-readonly.png new file mode 100644 index 000000000..5dc0e0a5e Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/016-live-form-questions-readonly.png differ diff --git a/design/features/welsh-version/screenshots-v2/1001-welsh-guidance-preview.png b/design/features/welsh-version/screenshots-v2/1001-welsh-guidance-preview.png new file mode 100644 index 000000000..8a1865787 Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/1001-welsh-guidance-preview.png differ diff --git a/design/features/welsh-version/screenshots-v2/1002-welsh-date-preview.png b/design/features/welsh-version/screenshots-v2/1002-welsh-date-preview.png new file mode 100644 index 000000000..361c70c25 Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/1002-welsh-date-preview.png differ diff --git a/design/features/welsh-version/screenshots-v2/1003-welsh-address-preview.png b/design/features/welsh-version/screenshots-v2/1003-welsh-address-preview.png new file mode 100644 index 000000000..496c675f8 Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/1003-welsh-address-preview.png differ diff --git a/design/features/welsh-version/screenshots-v2/1004-welsh-NI-preview.png b/design/features/welsh-version/screenshots-v2/1004-welsh-NI-preview.png new file mode 100644 index 000000000..dd7dadc79 Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/1004-welsh-NI-preview.png differ diff --git a/design/features/welsh-version/screenshots-v2/1005-welsh-cya-open-email-preview.png b/design/features/welsh-version/screenshots-v2/1005-welsh-cya-open-email-preview.png new file mode 100644 index 000000000..e23484710 Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/1005-welsh-cya-open-email-preview.png differ diff --git a/design/features/welsh-version/screenshots-v2/1005-welsh-cya-preview.png b/design/features/welsh-version/screenshots-v2/1005-welsh-cya-preview.png new file mode 100644 index 000000000..80f9f8308 Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/1005-welsh-cya-preview.png differ diff --git a/design/features/welsh-version/screenshots-v2/1006-welsh-confirmation-preview.png b/design/features/welsh-version/screenshots-v2/1006-welsh-confirmation-preview.png new file mode 100644 index 000000000..36dd4d363 Binary files /dev/null and b/design/features/welsh-version/screenshots-v2/1006-welsh-confirmation-preview.png differ diff --git a/design/features/welsh-version/screenshots-v2/README.md b/design/features/welsh-version/screenshots-v2/README.md new file mode 100644 index 000000000..96571c074 --- /dev/null +++ b/design/features/welsh-version/screenshots-v2/README.md @@ -0,0 +1 @@ +This folder is for screenshots for adding Welsh version of a form v2. The first release of Welsh translations diff --git a/design/features/welsh-version/version-2.md b/design/features/welsh-version/version-2.md new file mode 100644 index 000000000..79c99aaab --- /dev/null +++ b/design/features/welsh-version/version-2.md @@ -0,0 +1,299 @@ +# Add Welsh version of a form v2 - first release + +## Status + +Date created: 23 February 2026 + +Released + +___ + +## Contents + +- [Status](#status) +- [Contents](#contents) +- [What](#what) +- [Designs for development](#designs-for-development) +- [Form filler screens](#form-filler-screens) + +___ + +
+ +## What + +After our round of testing we agreed on what our first release for Welsh versions would look like. + +The team agreed we could go live without finishing all the designed parts of the journey and without requiring further testing of certain parts of the journey as these were considered low risk. + +This is a write up of the screens that were developed for our first release at the start of 2026. + +
+ + +### Things to note + +There are a number of key screens, journeys and parts of the feature that were not released as part of the first version. These include: + +- markdown editor not in place on the Welsh version page +- make your form live pages don’t currently show any content about the Welsh version + - there is also a next step iteration for making Welsh and English versions live at separate times that was not part of this release +- live read-only view screens not yet showing Welsh content +- archive the Welsh version of your form not developed +- group page not showing the forms with a Welsh version + +
+ + +## Designs for development + +### Create a form - task list + +Create a form task list page. Screenshot +Create a form task list page showing 1 of 9 tasks marked completed. + +Through our round of testing we were able to confirm the introduction of a new optional section to provide a task to add Welsh translations alongside the English content added to a form. + +The new section content reads: + +> 4\. Create a Welsh version of your form (optional) +> Add a Welsh version of your form + +The task link has a grey ‘optional’ tag to its right. This state will only appear if no Welsh has been added to the form. + + +### Add a Welsh version of your form - new form without any content + +Empty Add a Welsh version of your form page. Screenshot + +Add a Welsh version of your form page showing that no tasks have been completed in English yet. + +Under the page heading there’s a table component titled “Form name”. The table has 2 columns titled, “English content” and “Welsh content”. + +The next row shows the English form name added by the form creator on the left and a text input labelled “Enter your Welsh form name” on the right. + +This is a change from the original grey bordered tables from the tested iteration. We found that some form creators weren’t sure that they could change or add their translations into the boxes here, with one thinking they needed to go to aother page to add it. We believe that using the standard inputs on this screen will help make it obvious to form creators that this is the screen they should add translations to. + +After the form has just been created, the ‘add a Welsh version of your form‘ page can still be accessed. It just shows placeholder text at this point to say that nothing has been added yet. + +There's a section with a heading for each part of the form, they read: + +> Form questions +> No questions have been added to the form yet. +> +> Declaration for people to agree to +> No declaration has been added to the form. +> +> Information about what happens next +> No information about what happens next has been added to the form yet. +> +> Payment link +> No payment link has been added to the form. +> +> Link to privacy information for this form +> No privacy information has been added to the form yet. +> +> Contact details for support +> No contact details for support have been added to the form yet. + +The form creator can still technically save the page meaning a Welsh version ‘exists’ even though all the inputs may be empty at this point. + + +### Create a form - task list with Welsh version saved success banner + +Create a form task list page with saved Welsh success banner. Screenshot + +Create a form task list page showing a green success banner, “The Welsh version of your form has been saved”. + +The optional Welsh task is now marked as ‘in progress’. This will display if the Welsh page is saved with or without content being added - unless the Welsh version is deleted. + + +### Deleting a Welsh version + +Empty Add a Welsh version of your form page with delete button. Screenshot + +’Add a Welsh version of your form‘ page showing no English content yet but with a red ’Delete Welsh version‘ button after the Welsh was ‘saved’. + +To remove the Welsh version, whether empty or full, the form creator can use the new ‘delete’ button. + +
+ +Are you sure you want to delete the Welsh version of your form page. Screenshot + +’Are you sure you want to delete the Welsh version of your form‘ question page with ‘yes’ and ‘no’ radio options. + +
+ +Create a form task list page with deleted Welsh success banner. Screenshot + +’Create a form‘ task list page showing a green success banner, “The Welsh version of your form has been deleted”. + +The optional Welsh task has been reset to show the grey ‘optional’ tag. + + +### Add a Welsh version of your form - full English form created + +Empty Add a Welsh version of your form page. Screenshot + +’Add a Welsh version of your form‘ page showing all the English content completed with empty Welsh inputs alongside each bit of content. + +There is now a “Preview this form in Welsh” link beneath the page heading. This is designed to take the form creator to their form preview with the Welsh language toggle selected. + +In its current state, without any Welsh content, they would be taken to the Welsh version but only see the English content they added with the Welsh page furniture we automatically add. + +The page is built up of different tables which show the English content with a Welsh content input alongside. + +The first table is captioned “Form name”. It has 2 columns, one title “English content” and one “Welsh content”. + +The next row shows the English form name added by the form creator on the left and a text input labelled “Enter you Welsh form name” on the right. + +There are then 6 tables for each question added to the form. These have 3 columns where the first column is untitled. + +Question 1’s table shows a 3 column table: + +> Page heading : How to complete this form : Enter Welsh page heading (labelled input) +> +> Guidance text : (This shows the markdown added in English including the markdown syntax) : Enter Welsh guidance text (labelled input) +> +> Question text : What is your full name? : Enter Welsh question text (labelled input) + +Question 2’s table shows a 3 column table: + +> Question text : What is your date of birth? : Enter Welsh question text (labelled input) +> +> Hint text : For example, 20 3 2000 : Enter Welsh hint text (labelled input) + +Question 3’s table shows a 3 column table: + +> Question text : What is your address? : Enter Welsh question text (labelled input) + +Question 4’s table shows a 3 column table: + +> Question text : What is your phone number? : Enter Welsh question text (labelled input) + +Question 5’s table shows a 3 column table: + +> Question text : What is your National Insurance number? : Enter Welsh question text (labelled input) +> +> Hint text : It’s on your National Insurance card, benefit letter, payslip or P60. For example, QQ 65 43 21 C. : Enter Welsh hint text (labelled input) + +Question 6’s table shows a 3 column table: + +> Question text : If you live in Wales, would you like to hear from us in Welsh in future communications? : Enter Welsh question text (labelled input) +> +> Hint text : We will only use this if we contact you for more information. : Enter Welsh hint text (labelled input) + +As part of this version we changed the list of options inputs to be a separate table beneath the relevant question, in this case question 6. This is to make it more accessible to assistive tech users and allow us more flexibility going forward. We believe moving to this option covers the majority of form creators needs and keeps the table accessible. When we designed this option we wanted to be able to allow copy-pasting of lists that should automatically populate the table going down. This should simplify the amount of copying a form creator might need to do. + +This table is captioned “Question 6’s list of options”. It shows a table with 2 columns, for English and Welsh content: + +> Yes : Enter Welsh option 1 (labelled input) +> +> No : Enter Welsh option 2 (labelled input) +> +> Not applicable : Enter Welsh option 3 (labelled input) + +Below the question tables are the other sections of the form that content needs to be added to by the form creator. + +“Declaration for people to agree to” captioned table with 2 columns for English and Welsh content: + +> (English declaration from form fillers to agree to) : Enter your Welsh declaration (labelled textarea input) + +“Information about what happens next” captioned table with 2 columns for English and Welsh content: + +> (English information about what happens next that form fillers see on the confirmation screen) : Enter information about what happens next in Welsh (labelled textarea input) + +“Link to privacy information for this form” captioned table with 2 columns for English and Welsh content: + +> https://www.gov.uk/help/privacy-notices : Enter link to your Welsh privacy information (labelled textarea input) + +“Contact details for support” captioned table with 3 columns, this first without content and the other 2 for English and Welsh content: + +> Text to describe the contact link : Our full contact details : Enter text to describe the contact link for Welsh support (labelled textarea input) +> +> Online contact link : https://www.gov.uk/contact-us : Enter an online contact link for Welsh support (labelled textarea input) + +The page ends with the “Have you finished adding your Welsh version?” question. It has hint text: “Selecting ‘Yes’ will mark this task as complete. You’ll still be able to make more changes if you need to.” There are 2 radios: + +> Yes +> No, I’ll come back later + +Finally there’s a green “Save and continue” button. + +
+ + +Completed Add a Welsh version of your form page. Screenshot + +’Add a Welsh version of your form‘ page showing all the inputs have a Welsh translation in their corresponding input boxes. The Welsh content has been saved which means a red “Delete Welsh version” button now appears alongside the “Save and continue” button. + + +### Create a form - saved and completed Welsh version + +Create a form task list page showing Welsh version changes saved. Screenshot + +Task list screen showing a green success banner, “The Welsh version of your form has been saved”. + +
+ + +Create a form task list page showing Welsh version saved and marked completed. Screenshot + +Task list screen showing a green success banner, “The Welsh version of your form has been saved and marked complete”. + + +## Form filler screens + +### Previewing a form + +First question page in a form with more complex guidance before the question. Screenshot + +First question page in a form with guidance before the question and ‘Cymraeg’ language toggle selected. + +
+ + +Date of birth question page in Welsh. Screenshot + +Date of birth question page in a form. The ‘Cymraeg’ language toggle is selected. + +
+ + +Address question page in Welsh. Screenshot + +Address question page in a form. The ‘Cymraeg’ language toggle is selected. + +
+ + +Check your answers before submitting page in Welsh. Screenshot + +’Check your answers before submitting‘ page in a form. The ‘Cymraeg’ language toggle is selected. + +
+ +Your form has been submitted page in Welsh. Screenshot + +’Your form has been submitted‘ page in a form. The ‘Cymraeg’ language toggle is selected. + + +### Previewing a form with English content but no Welsh + +First question page in a form with guidance showing the English version. Screenshot + +First question page in a form with guidance showing the English content and ‘English’ language toggle selected. + +
+ +First question page in a form with guidance showing English while the Welsh version toggle is selected. Screenshot + +First question page in a form with guidance showing the English content added by the form creator while the ‘Welsh’ language toggle is selected. The page furniture that is not added by the form creator, such as the banner message and button text, displays in Welsh. + +
+ +___ + +
+ +[Back to the top](#add-welsh-version-of-a-form-v2---first-release) diff --git a/diagrams/class-diagrams/runner.md b/diagrams/class-diagrams/runner.md index 97d21e042..99e4f5d3f 100644 --- a/diagrams/class-diagrams/runner.md +++ b/diagrams/class-diagrams/runner.md @@ -7,14 +7,22 @@ title: GOV.UK Forms Runner app class diagram ```mermaid classDiagram - direction RL - class `Submission` - `Submission` : +jsonb answers - `Submission` : +jsonb form_document - `Submission` : +integer form_id - `Submission` : +string mail_message_id - `Submission` : +string mail_status - `Submission` : +string mode - `Submission` : +string reference - `Submission` : +datetime sent_at + direction RL + class `Delivery` + `Delivery` : +datetime delivered_at + `Delivery` : +string delivery_reference + `Delivery` : +datetime failed_at + `Delivery` : +string failure_reason + `Delivery` : +datetime last_attempt_at + class `Submission` + `Submission` : +jsonb answers + `Submission` : +jsonb form_document + `Submission` : +integer form_id + `Submission` : +string mode + `Submission` : +string reference + `Submission` : +string submission_locale + class `SubmissionDelivery` + `Submission` --> `SubmissionDelivery` + `Delivery` --> `SubmissionDelivery` + `Submission` "0..*" -- "0..*" `Delivery` ``` diff --git a/diagrams/sequence-diagrams/sending-submission-emails.md b/diagrams/sequence-diagrams/sending-submission-emails.md index 472d4087a..95d9684f3 100644 --- a/diagrams/sequence-diagrams/sending-submission-emails.md +++ b/diagrams/sequence-diagrams/sending-submission-emails.md @@ -75,8 +75,7 @@ break error end ses->>worker: return message_id -worker->>runner-db: set mail_message_id on Submission -worker->>runner-db: set the last_delivery_attempt timestamp on Submission +worker->>runner-db: create a Delivery record with the
message_id from SES as the delivery_reference ses-)inbox: send email note over ses,inbox: happens some time later @@ -90,7 +89,7 @@ else email bounces note over ses,sns: We have an SQS queue subscribed to the
SNS topic and a recurring task to poll
the SQS queue. end -worker->>worker: Recurring task deletes Submissions
that haven't bounced after 7 days +worker->>worker: Recurring task deletes Submissions
30 days after they were created ``` ## Handling email bounces/complaints @@ -116,15 +115,15 @@ worker->>solidqueue-db: enqueue recurring receive bounces job worker->>solidqueue-db: dequeue receive bounces job worker->>sqs: get messages from bounces and complaints queue alt there is a bounce SQS message - worker->>runner-db: get Submission by the message_id in the SQS message - worker->>runner-db: update delivery_status of Submission to "bounced" + worker->>runner-db: get Delivery where the delivery_reference is the
message_id from the SQS message + worker->>runner-db: set the failed_at timestamp on the Delivery worker->>worker: Log with the submission details worker->>sentry: send error event sentry->>support: Alert via Slack support->>support: Identify why the email bounced support->>support: Run rake task to retry submission else there is a complaint SQS message - worker->>runner-db: get Submission by the message_id in the SQS message + worker->>runner-db: get Delivery where the delivery_reference is the
message_id from the SQS message worker->>worker: Log with the submission details end @@ -152,7 +151,8 @@ actor support as Forms team tech support worker->>solidqueue-db: enqueue recurring receive deliveries job worker->>solidqueue-db: dequeue receive deliveries job worker->>sqs: get messages from deliveries queue -worker->>runner-db: get Submission by the message_id in the SQS message +worker->>runner-db: get Delivery where the delivery_reference is the
message_id from the SQS message +worker->>runner-db: set the delivered_at timestamp on the Delivery worker->>worker: log a "form_submission_delivered" event note over worker,runner-db: we don't currently use the "delivered" status for anything other than for information ``` diff --git a/diagrams/state-diagrams/welsh-translation-states-and-fields.md b/diagrams/state-diagrams/welsh-translation-states-and-fields.md new file mode 100644 index 000000000..0bc99fc27 --- /dev/null +++ b/diagrams/state-diagrams/welsh-translation-states-and-fields.md @@ -0,0 +1,53 @@ +# Adding Welsh to a Form + +This document describes how adding a Welsh translation affect a form and it's form documents. + +## The Welsh tasklist status + +The Welsh task is optional. If the form creator does nothing, it will not block the form from being made live. + +If the task is started, by entering any values into the translation screen and submitting it as unfinished, the status will be set to in progress. + +The form cannot be made live while the Welsh task is in progress. + +If the task is completed, by entering a full translation of the form and submitting it as finished, the status will be set to complete and the form can be made live. + +Any changes to the form or translation which would mean that the Welsh is no longer complete, such as adding a declaration, new question, exit page or support method will +set the status to in progress. + +```mermaid +stateDiagram-v2 + Optional --> In_Progress:Enter Welsh, save unfinished + Optional --> Complete:Enter Welsh, save finished + Complete --> Optional:Delete Welsh + In_Progress --> Optional:Delete Welsh + In_Progress --> Complete:Enter Welsh, save unfinished + Complete --> In_Progress:Invalidate Welsh +``` + +## New fields on Form + +## available_languages + +`available_languages`, is an array of language codes. It's `["en"]` by default, which signals that the form is only available in English. +Forms with a Welsh translation have `["en", "cy"]` in the array. + +As soon as the Welsh translation page is submitted with at least one value for a field, the `available_languages` array will be updated. + +The `available_languages` array is used when generating form documents, which are used by the runner. Form documents are created for each language in the array. +It's updated when the Welsh translation is submitted so the user can immediately preview the Welsh translation, even if they haven't completed it. + +The `available_languages` array is saved in form documents. It's used by the runner to discover that the form is available in Welsh, if it's showing the English version. + +### welsh_completed +`welsh_completed` is a boolean, which is records if the form creator has marked the Welsh as complete. It's not included in form_documents. + +## Places where the values change + +If the English form changes, we need to update the Welsh translation to match. This can happen if the form creator deletes a field, such as a declaration. +To keep the Welsh translation in sync, Form has a new method +`normalise_welsh!`. It's called when the form documents for draft or live are +made. It ensures that the Welsh translation doesn't have any values which the +English form doesn't have. + +The method on Form in turn calls `normalise_welsh!` on each page and condition, which syncs these values.