Contributing to the Playbook
What you will need
- A GitHub account
- To be invited to the dxw organisation
- 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:
- Present our ideas against those existing
- Discuss other people’s ideas
- Find agreement and get things changed
- 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
- View the main GitHub page
- Go to the folder where you want to add a new file
- Click ‘Create new file’
- Add your new content using the markdown syntax
- Commit your change (scroll to the bottom)
- Give the commit a short title
- Include more detailed reasoning and explanations in the description
- Select
Create a new branch for this commit and start a pull request.
- Commit changes
- Open a pull request
- Make sure the title explains the small change you’re suggesting
- Write a short comment to encapsulate the whole change
- Create a pull request
Edit
- Find the file you want to change in GitHub
- Go into edit mode (click the pencil)
- Make your change
- Commit your change (scroll to the bottom)
- Give the commit a short title
- Include more detailed reasoning and explanations in the description
- Select
Create a new branch for this commit and start a pull request.
- Commit changes
- Open a pull request
- Make sure the title explains the small change you’re suggesting
- Write a short comment to encapsulate the whole change
- 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.
- To see the open pull requests, visit https://github.com/dxw/playbook/pulls
- Click on the name of the pull request you want to review
- The page for an invididual pull request has several tabs, the most important
ones are
Conversation
andFiles changed
. Take the time to read the pull request description (in theConversation
tab) to understand why this change was made, and any futher comments on this page. - 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 onView file
(top right) to see the amended Playbook as a whole. - If you are happy with the changes, click on the green
Review changes
button in the top right. Select theApprove
radio button and add any comments you have about the changes. Then clickSubmit review
. - If you think the changes need more work before merging, click on the
Review changes
button and select theRequest changes
radio button. Use the comment form to let the editor know what changes you wish to see, then clickSubmit review
. The editor will recieve notification of your comments. - When you are happy with the changes in the pull request, you can click the
green
Merge pull request
button on theConversation
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.