How to create a brief

In GitHub we use “parent” issues to host our cycle briefs. This creates a hierarchy where we can create sub-issues which form the deliverables of a brief.

In the majority of cases, the brief will already have been created by a team lead. However, there may be occasions when you need to create a brief yourself. This guide explains how.

Choosing the appropriate GitHub repository to create the brief in

The context of the brief you’re creating will determine the repository you create it in.

• for a brief specific to GOV.UK Frontend, use the govuk-frontend
• for a brief which is regarding GOV.UK Prototype Kit, use govuk-prototype-kit
• for a brief specific to the Frontend docs, use govuk-frontend-docs
• for a brief regarding the Brand Guidelines website, use govuk-brand-guidelines
• for a brief specific to the team playbook, use design-system-team-docs

If a brief is sensitive and should not be seen by people outside of the team, use design-system-team-internal. This repository is private and used only by members of the Design System team.

If a brief is specific to the Design System website, use the govuk-design-system repo. If your brief cannot be categorised by any of the other repos, also use the govuk-design-system repo.

Creating a brief

Step 1: Navigate to the “Issues” tab.

Step 2: Select the green “New issue” button.

Step 3: Select the “Cycle brief” template.

Step 4: Complete the “## Brief” section which contains a prompt about the content you should include.

Step 5: Complete the “## Squad” section by tagging your fellow squad members via their GitHub username.

Step 6: Complete the “## Further detail” which contains a prompt about the content you should include.

Step 7: Attach “Assignees” to the brief (these are your fellow squad members). This feature may be found either at the bottom of the pop-up window or on the right side-navigation of the issue.

Step 8: Add the appropriate labels (guide coming soon).

Step 9: Add a “Project” board. In most cases this should be “GOV.UK Design System cycle board”.

Step 10: Select the green “Create” button to open your issue.

After the brief has been created, double check it has been set up correctly by reviewing the right side-navigation to check all the appropriate metadata is showing.

Under the “Projects” sub-section, you may need to update the “Status” field on the “GOV.UK Design System cycle board” to “Backlog”.

There is no need to use the “Type” field at present — you can leave this blank.

Note that your brief will not appear on the cycle board until you add a sub-issue. Read the guide here about creating sub-issues.

Watch a demo

To see a demonstration of this in action, you can watch a recording of a team learning & development session here.