Contributing to the playbook
About the playbook#
The playbook is made using Docusaurus and GitLab this means that anyone at AND can contribute to the play book. We encourage everyone to contribute as it will always be a work in progress.
It's really hard to break things, and your changes will be peer reviewed so which will help find any bugs or errors.
Getting a GitLab account#
You need a GitLab account to be able to contribute to the Playbook. Visit GitLab to sign up for an account. You can use your AND email address or sign in with a personal account.
Accessing the Repo#
Everyone at AND with a GitLab account can access to download and suggest edits to the playbook. If you have just made a GitLab account then post in the cop-ux channel on slack and someone will be able to help.
You can find the playbook repo here.
How to suggest edits#
There are two ways to suggest edits to the Playbook.
- Online using the web editor
- On your computer using a Code Editor
Both ways will allow you to edit the playbook. Editing on your computer will allow you to see changes before they are merged and deployed to the live site but if you are new to GitLab then you may find it easier to edit the playbook online.
Editing the playbook online#
- Go to the Playbook repository
- Navigate to the docs folder and open the page that you want to edit.
- Click the Edit button
- Make your change
- Add in a name for the target branch such as up-date-to-about-playbook. GitLab will show a tick box that will start a new merge request. We want this box to be ticked, so that your changes can be reviewed and applied.
- Click Commit Changes.
- You will be taken to a new merge request screen. Add a description to explain what the changes are about then click Create merge request
- Copy the URL of the merge request and paste it in the cop-ux channel on slack
The URL should look like
https://gitlab.com/ANDigital/murray/murray-playbooks/ux-playbook/-/merge_requests/29
Editing the playbook on your computer#
You may want to ask a developer for help with this. Ask in the cop-ux channel on slack
- Download a code editor such as VS Code, or Atom or (Sublime)[https://www.sublimetext.com/].
- Make a new SSH Key or use an existing key.
- Open Terminal and clone the repository to your computer.
- Install the latest version of Node using Node Version Manager
- Start the site by using the command
npm startin Terminal - Edit the pages using your code editor
- Commit and push the changes to GitLab
- Create a merge request and paste it in the cop-ux channel on slack
Best practice#
When updating the playbook there are a few files that should be updated to help keep the site easy to maintain.
Changelog.md#
The changelog file should be updated to include a brief description of what changes were made and why. It can be found in the root (top level ) of the repo.
Always add your entry at the top of the file so that the most recent changes are seen first. You can see an example of an entry below. It starts with a version number and date, then the author of the change and a link to their gitlab profile, finally we have a short description of what has been added or changed.
package.json#
In the changelog we specified a new version number for our change, we need to do the same thing in this file. Update the version at the top of the file to match the one you have added to the changelog.md file.
sidebars.js#
This file is used to generate the site navigation and only needs to be updated when adding or moving existing pages. In the example below individual pages are items, we are adding MY-NEW-PAGE to the tools and software category. Each page is separated by a comma.