Propose a content change using GitHub

Contents

  1. How we manage content in this playbook
  2. 1\. Go to the page you want to edit
  3. 2\. Edit the page file
  4. 3\. Propose your change
  5. 4\. Confirm your changes
  6. 5\. Create a pull request
  7. 6\. Wait for the team to review your pull request

# How we manage content in this playbook

We use a service called GitHub to manage content in the NHSBSA Playbook.

This guide explains how to propose a change to the Playbook’s content, for instance if you spot a spelling mistake or you want to add something to it. You’ll need a GitHub account to do this.

If you do not have one already, you can create a GitHub account for free.

Don’t worry, it’s impossible for you to break the Playbook by proposing changes. The Digital Delivery Leads team reviews all changes before publishing.

If you get stuck whilst following these steps and you need help, you can:

  • get in touch on #playbook channel on the NHSBSA Slack
  • catch one of the design team in person at the communities of practice

# 1. Go to the page you want to edit

At the bottom of every page in the Playbook you will find a section called ‘Help improve this page’.

Follow the link to propose a change to the page. This will take you to the page’s Markdown file.

You might be told you need to fork the Playbook repository to make changes. This is nothing to worry about. It just means you’re making a copy of the Playbook that you can edit. Select “fork this repository and propose changes” to continue.

Screenshot of the 'folk this repository' notification, with button highlighted

# 2. Edit the page file

Edit the Markdown to make your change.

Here is an example showing how to update the description of the checkboxes component.

The checkboxes description in the file in GitHub with an uppercase C in the word checkboxes
In this example, the uppercase ‘C’ on the word ‘Checkbox’ has been changed to lowercase.

The checkboxes description in the file in GitHub after the C in the word checkboxes has been changed to lowercase

# 3. Propose your change

Once you’re happy, find the section called ‘Propose file change’ at the bottom of the page.

Add a short description explaining the reason for your change in the first field. This information will be added to the file’s changelog. Try to be as clear as possible, to help future users understand the update.

If you need to provide more information about your change, you can add more detail in the larger field below.

Propose file change view in GitHub. There is a summary of the change and a longer description beneath it. There are 2 buttons, one with the option to propose the change and one to cancel it.
When you are happy with your description, select ‘propose file change’. You’ll have a chance to review and confirm your changes on the next page.

# 4. Confirm your changes

You’ll be shown a confirmation page where you can review the changes you’ve made.

If you spot a mistake, you can go back to the previous page and correct it.

If you are happy with your changes, select ‘Create pull request’. You’ll have one more chance to review your change on the next page before you submit it to the NHSBSA Playbook team to review.

Create pull request view in GitHub showing a before and after view of the file you have changed and a button labelled create pull request.

# 5. Create a pull request

A pull request is a request to the NHSBSA Playbook team to add (‘pull’) your changes into the project and publish them in the Playbook.

Once you’ve created a pull request, your proposed change and any comments you’ve written will be publicly visible meaning that anyone can see them on GitHub.

You’ll see the description you entered in step 3 and can add some additional information if you want to.

Once you’re happy, select ‘create pull request’.

Create pull request view in GitHub. It is pre-filled with the summary and the description from the previous propose change view. There is a button to create a pull request.

# 6. Wait for the team to review your pull request

The NHSBSA team will be notified of your suggestion and will review it.

The team will either:

  • accept your proposal and publish your change straight away
  • accept your proposal but ask for some changes before publishing
  • not accept your proposal and explain why