How to contribute to the DevTools Design System Documentation

Changing an existing page - GitHub UI

The repository is at: devtools-html/photon

You can test locally with localhost but if you’re adding just content then it should be fine

Pages make use of includes, links to content from other files (typically .md markdown files)

Markdown Cheatsheet

1. Edit the .md file in the Github editor, the page markdown files are located in photon/jekyll
2. When you’re happy with your changes fill out a Commit changes comment at the bottom
3. Click the Create a new branch for this commit radio button so that your amends aren’t committed direct to master. Give your branch a name.
4. Click the Propose file change button.
5. Submitting the page takes you to the the Open a pull request page where you can ask for reviewers. You can ask Blake Winton, Victoria Wang or Matt Croud for a review.
6. To end your submission click the Create the pull request button.

A notification will be sent to either Blake, Victoria or Matt. We will check the files changed and leave comments for feedback if necessary.

In general, Blake will carry out merges.

There are two methods for Creating a new page. You can simply use the Github UI or Checkout the Repository create the page locally.

Adding a new Page - GitHub UI

1. In the repository travel to the category you wish to add a new page to e.g. photon/jekyll/_motion/
2. Click the Create new file button at the top of the page.
3. The first thing to do is to add a front matter snippet at the top of your page (example below). Front matter is metadata for Jekyll that makes your page function. With the front matter in place, change the title and order values as required. Front matter template:

   ---
   layout: page
   title: Duration and Easing
   order: 1
   ---

   You should also add the optional draft : true flag to highlight your page as a draft.
4. When you’re happy with your changes fill out a Commit changes comment at the bottom
5. Click the Create a new branch for this commit radio button so that your amends aren’t committed direct to master. Give your branch a name.
6. Click the Commit new file button.
7. On the Open a pull request page (pictured below) provide a message and mention either @violasong @mcroud or @bwinton for review. [add image here]
8. To end your submission click the Create Pull Request button.

Adding a new Page - GitHub Checkout

As a rule of thumb, try to copy snippets and layout code from existing pages e.g. For a two column layout use the markdown from the existing principles page (jekyll/_includes/introduction/principles.md)

1. Checkout the project on Github so you have a local copy and make a new branch.

   git clone https://github.com/devtools-html/photon.git
   git checkout -b branch_name

2. It is a good habit to run git pull to ensure your local copy is up to date.
3. Go into jekyll folder and add your new .md page under the appropriate category.
4. The first thing to do is to add a front matter snippet at the top of your page (example below). Front matter is meta data for Jekyll that makes your page function. With the front matter in place, change the title and order values as required. Front matter template:

   ---
   layout: page
   title: Duration and Easing
   order: 1
   ---

   You can can also add the optional draft : true flag to highlight your page as a draft.
5. Complete your document in markdown You can use docker to run a local copy if you want to preview your work locally, Docker set up information is available in the README.md
6. Include other files using this syntax: {% include introduction/example.md %} to keep pages smaller more manageable. Include files are stored in the _includes folder.
   Two common includes are:
   {% include global/do.md %}
{% include global/dont.md %}
   Which add DO and DONT headers to the page.
7. When your happy to submit your page; git add your file, ready for committing.

   git add <filename>

8. Git commit your changes

   git commit -m "Commit message"

9. Push the changes to origin specifying your new branch:

   git push origin <branch-name>

10. On the github repo page you should see the new branch notification message, click the Compare and pull request button, provide a message and mention either @violasong @mcroud or @bwinton for review. Click Create Pull Request.
11. If there is feedback for your pull request you will be notified by comment. If there is no feedback your submission will be merged.
12. Your branch will be deleted once it is merged so remember to create a new branch for future amends.