Contributing to the Playbook

What you will need

  1. A GitHub account
  2. To be invited to the dxw organisation
  3. To be invited to the staff team

Why GitHub?

We are all encouraged to help shape dxw and help it grow. The decisions we make are represented in the Playbook so it’s important to have an open and collaborative means to evolve it.

GitHub allows us to:

  1. Present our ideas against those existing
  2. Discuss other people’s ideas
  3. Find agreement and get things changed
  4. Store a history of our decision making

Decide if new content is for the Playbook

It’s in the Playbook if

  • it’s a principle explained in plain english.
  • it’s something we want to/are comfortable to share outside of dxw.
  • we want it to be visible to the wider team.
  • it’s user research or design glossary.

It’s in guides if

  • it’s a detailed, step by step instruction.
  • we’re talking about something specialist. This could mean we are using jargon and referring to community-known methods and ways of working.

It’s something else if

  • it’s something visual and reusable, it will likely belong in the brandbook.
  • it’s a good, work-related read, there may be a repository to put it in.
  • it’s a poster it should be succinct, large-print friendly and something we want to share with the wider dxw team. It’s also something we want clients to see and understand. It belongs in the brandbook.

Create

  1. View the main GitHub page
  2. Go to the folder where you want to add a new file
  3. Click ‘Create new file’
  4. Add your new content using the markdown syntax
  5. Commit your change (scroll to the bottom)
    1. Give the commit a short title
    2. Include more detailed reasoning and explanations in the description
    3. Select Create a new branch for this commit and start a pull request.
    4. Commit changes
  6. Open a pull request
    1. Make sure the title explains the small change you’re suggesting
    2. Write a short comment to encapsulate the whole change
    3. Create a pull request

Edit

  1. Find the file you want to change in GitHub
  2. Go into edit mode (click the pencil)
  3. Make your change
  4. Commit your change (scroll to the bottom)
    1. Give the commit a short title
    2. Include more detailed reasoning and explanations in the description
    3. Select Create a new branch for this commit and start a pull request.
    4. Commit changes
  5. Open a pull request
    1. Make sure the title explains the small change you’re suggesting
    2. Write a short comment to encapsulate the whole change
    3. Create a pull request

Merging pull requests

When the create or edit steps are followed the result is a pull request, which is essentially a request for a change to be added to the Playbook. Merging a pull request means accepting a change into the Playbook.

Anyone who is part of the staff team on Github can approve and merge pull requests.

  1. To see the open pull requests, visit https://github.com/dxw/playbook/pulls
  2. Click on the name of the pull request you want to review
  3. The page for an invididual pull request has several tabs, the most important ones are Conversation and Files changed. Take the time to read the pull request description (in the Conversation tab) to understand why this change was made, and any futher comments on this page.
  4. Click on Files changed to see the actual changes made to the Playbook. Lines removed will be marked in red, and lines added marked in green. If you want to see the changes in context, click on View file (top right) to see the amended Playbook as a whole.
  5. If you are happy with the changes, click on the green Review changes button in the top right. Select the Approve radio button and add any comments you have about the changes. Then click Submit review.
  6. If you think the changes need more work before merging, click on the Review changes button and select the Request changes radio button. Use the comment form to let the editor know what changes you wish to see, then click Submit review. The editor will recieve notification of your comments.
  7. When you are happy with the changes in the pull request, you can click the green Merge pull request button on the Conversation tab.

The Playbook is hosted on GitHub Pages, and it’s tracking the main branch. This means changes will be published automatically when a pull request is merged.