Contributing to patternfly org for designers

These instructions cover the process for contributing design guidelines to patternfly.org.

Goals of PatternFly design guidelines

Design guidelines should give designers general usage guidelines for designing with PatternFly, as well as:

• Identify relevant components and describe how they can be used together to solve a particular use case.
• Define best design practices and explain how these can be used with components and patterns.
• Address common issues in the design and provide advice for determining the proper solution.

When you’re ready to contribute, follow these steps:

First time set up instructions [do this once only!]

Step 1: Set up your code editor and GitHub account

Before you can contribute content, you’ll need to set up your code editor and GitHub account. These instructions follow using Microsoft Visual Studio Code as your code editor, but if you prefer using a different code editor, feel free to do so.

1. Download Microsoft Visual Studio Code (VSC).
2. Open Microsoft Visual Studio Code (VSC).
3. Create a GitHub account if you don’t already have one.
4. Once you created your account and logged in, go to the patternfly-org GitHub repo.
5. In the top right-corner under your GitHub icon, click Fork. Learn more about GitHub terminology and concepts.

Step 2: Get patternfly-org on your local

1. Add a folder in your computer’s Documents folder to store the repository content, and name it “repos”.

Now, you’ll have to set up your local contribution environment. You will only need to do this once. Open your computer’s terminal and follow these steps:

2. Type pwd and press Enter. This tells you where you’re located within your computer, like which directory you’re in and what files are listed there.

3. Change directories based on where you want to install the repo. To install to /Users/username/documents/repos, type cd documents, press Enter, type mkdir -p repos, press Enter, type cd repos, and press Enter.

4. Type git clone, followed by your patternfly-org GitHub URL. For example, if your github name is mmenestr, you would type in: git clone https://github.com/mmenestr/patternfly-org.git

   a. When submitting the command, you may get a pop-up prompting you to install something. If you do, click Install and follow the instructions from there.

   

   b. Once you're done installing, re-type the following command, remembering to replace “yourGitHubname” with your GitHub name: git clone https://github.com/yourGitHubname/patternfly-org.git, Press Enter.

5. Type cd patternfly-org and press Enter.

6. Type git remote add upstream https://github.com/patternfly/patternfly-org.git and press Enter.

Step 3: Prepare your VSC

1. To get your VSC ready, you will want to open up the patternfly-org file in your local computer. To do this, Go to File > Open.

   

2. From there, the following finder menu should pop-up. Look for your local “patternfly-org” folder, and press Open. This will open up the right files inside your VSC.

   

3. To configure your VSC so that all your changes are saved automatically, go to your VSC Settings via: Code > Preferences > Settings.

   

4. Once on the Settings window, you should see a "Files: Auto Save" section set to "off". Open the dropdown menu and select "afterDelay". Now everytime you make a change, it will save automatically.

   

Preparing for PR creation

Step 4: Draft your document

Begin working on your issue by surveying approaches and typical use cases related to your topic. Gather examples and review how projects currently address your problem or situation. You should also research industry best practices related to your topic.

Once you have gathered some information, and before you create a PR, you will want to create a draft of the edits you plan on making. You can create a draft using Google Docs or a similar word processor and share it with mmenestr@redhat.com for review. It is also good practice to link this draft document to your GitHub issue for visibility and tracking.

Step 5: Create/update image assets

All image assets that currently exist on the PatternFly website are stored in this Design Doc Assets file file from the Sketch Cloud.

If you need to create new images as part of your issue/PR:

1. Open the latest version of the Design Design Doc Assets file from the Sketch Cloud by clicking “Edit in Sketch”. This file contains all of the assets needed to create and maintain images used within design documentation. You can edit the file directly, and the updates will automatically sync up to the cloud.

2. If a Sketch page for your component is already created, open it. If not, create a new page for keeping all your topic images. Name that page with the title of your documentation page—it will be used for displaying the topic in the navigation. For example, if you are creating images for a new component called “New component”, you would create a page in the sketch file called “New component”.

   

3. Insert a new artboard for every unique image that you will create.

4. Create your images. There are two types of images used within design guideline documents:

   • High-fidelity mockups are used to show component details or in any situation where understanding design specifics is important. When describing a design, add numbered callouts to point to specific elements. Note: If you're only pointing to one element, add an unnumbered callout instead.

     

     When creating high-fidelity mockups, you should first look for existing examples in the PatternFly template file. You can create new examples as needed by using the components found in that file. Just copy and paste artboards from the PatternFly template file, to the Design Doc Assets file. You can make callouts or other customizations there as needed.

   • Schematic mockups convey placement of elements in a page. These are useful when the internal content is not important or relevant. Because they lack text and graphics, schematic mockups also scale well when placed in a document. The example below demonstrates how the positioning, rather than the content, of a toast alert is the focus. You can find symbols for creating these in the “UI elements” page of the Design Doc Assets file.

   

5. When finished, your organization should look like this:

   

If you need to update existing images:

1. Download the latest version of the Design Doc Assets file from the Sketch Cloud.
2. Locate the page for the component you are working on, and find and update the images directly from there.

Create a PR, or update an existing one

Step 6: Begin a new pull request (PR) or edit an existing one

In order to make changes or additions to PatternFly design guidelines, you will need to create a pull request (PR). All of PatternFly org’s content lives in the main PatternFly branch. This main branch is the source of truth - it is the original content that you see displayed on the website. When you create a PR, you will go through the process of creating your own branch off of the main branch where you will be able to make your edits. Therefore, when you create a pull request, you are essentially making a request to the system to pull your updated content from the branch you created, into the main PatternFly branch.

To create a new PR:

1. Open up Visual Studio (VSC). If no folder seems to be opened within VSC, follow Step 3 above.

2. Navigate to the right directory in one of two ways:

   • First method: go to your patternfly-org folder in your finder, right click on it, and click “New terminal at folder”. Then write the command git checkout main. Press Enter.

     

   • Second method: Open up your terminal, and use it to enter the correct directory. The cd command you will be using is essentially navigating you to the folder you will be working out of for your PR - the patternfly-org folder you have on your local computer.

     Depending on where your patternfly-org repo folder lives in your computer, you will want to use your terminal to enter the correct directory.

     If your folder lives in Users/username/repos/patternfly-org, here are the commands you should enter:

     1. cd repos. This navigates to the repos folder your patternfly-org folder lives in.
     2. cd patternfly-org. This navigates to the patternfly-org folder.
     3. git checkout main. This checkout command will start you off in the correct branch - the main PatternFly branch that you will be working off of.

     If your folder lives in Users/username/documents/repos/patternfly-org, here are the commands:

     1. cd documents
     2. cd repos
     3. cd patternfly-org
     4. git checkout main

3. In your terminal, enter commands to grab the most updated version of the main branch:

   1. git fetch upstream. This fetches the latest changes from the main branch.
   2. git merge upstream/main. This merges the latest changes to your local branch.
   3. git push

   If this is your first time creating a PR, one of two things may occur:

   1. First possibility: You may get the following pop up when doing git push. If so, click Allow.

      

      Then click Authorize Visual-Studio-Code if/when prompted.

      

   2. Second possibility: You may get the following message after writing these commands: Username for https://github.com:.

   • If you get this, type in your github username, then press Enter.
   • Then in the following field DO NOT type in your regular github account passpower, instead, create a token by following these instructions.
   • For step 7 of the instructions, set it to never expire
   • For step 8 of these instructions, check all the fields.
   • Once you have your personal access token code copy it, then paste it in the password field, and press Enter. WARNING! The password field will not show anything while you type, so make sure you are careful/paying attention. Just because nothing is showing up does not mean it did not go through.

4. Create a new branch by typing git checkout -b [name of your branch] and press Enter. For example, if your branch name is iss2020, you would type git checkout -b iss2020 . (Name your branch your issue number, so if your issue number is 1234, name your branch “iss1234”).

5. Edit files in your Visual Studio Code (VSC) application.

To update an existing PR:

1. Follow bullets 1 and 2 of creating a new PR. (ie: type in the cd commands to navigate your terminal to the right folder)
2. Pull up the branch you created the PR in by typing git checkout [name of your branch]. For example, if your branch name is iss2020, you would type git checkout iss2020.
3. Edit files in your Visual Studio Code (VSC) application.

Step 7: Create or edit a file

Design guidelines are stored with other website content in the patternfly-org GitHub repo. Files in this repo adhere to the following file structure:

├── packages
│   └── v4
|       └── patternfly-docs
|           └── content
|               └── accessibility
|               └── contribute
│               └── design-guidelines
|                   └── charts
|                   └── components
│                       └── {topic-name}
│                           └── img
│                               └── {image-1}.png
│                               └── {image-2}.png
│                               └── ...
│                           └── {topic-name}.md
│                   └── content
│                   └── demos
│                   └── layouts
│                   └── styles
│                   └── usage-and-behavior

Note: Items not ending in a file extension are folder names.

Design guideline documents are located in content > design-guidelines folder. There are seven subfolders:

1. Charts: Guidelines for different chart types
2. Components: Component design guidelines (most likely what you will be updating)
3. Content: Guidelines for UX-Writing, and writing microcopy
4. Demos: Guidelines for demos
5. Layouts: Guidelines for layout types
6. Styles: Visual design resources and styles
7. Usage and Behavior: Interaction design patterns If you're creating a new file, name it [design].md in Visual Studio Code, replacing “design” with the name of your guideline exactly as you want it to appear in the website’s navigation.

Most likely, you will be working within the “Components” folder. Within this folder, each component has its own respective folder which contains:

1. An “img” folder for images where all images used in that component’s design guidelines are stored.
2. An md file, which is the markdown file for that component, in which you will make your text/image edits.

For example ,you can see in this image, that the “About modal” component has its own folder, containing an image (img) folder and markdown (.md) file.

If you're creating a new file:

1. Open up the “Components” file using the help of the directory above.
2. Create a new folder by right clicking on the components node, and clicking “New folder”. Name it the name of the component you are adding guidelines too. All folder names should be in lowercase with dashes in place of spaces.

3. Inside this folder, create (1) an md file named after the component you will be adding guidelines to (For example, "testing-test.md") and (2) a folder titled "img" where you will be storing all the images inserted in the guidelines. All Markdown file names should be in lowercase with dashes in place of spaces.

For example: if you are creating guidelines for a component called “testing-test”, your file structure would look like this:

4. Open up the md file you have just created and add the following code at the top of the document. (Your md file must contain the following front matter code at the top of the file in order to display properly in the page navigation.)

---
id: Your topic name
section: Where this lives in the above structure, e.g. "components"
---

For example, if you wanted to create a new file for the testing-test component, it would look like this:

---
id: Testing test
section: components
---

If you’re editing an existing file:

1. Locate the folder for the component in Visual Studio Code
2. Open the markdown file inside the folder, and edit from there.

Step 8: Export and add image assets

To ensure high-quality images in the final documentation, export sketch images as PNG x2. (Exporting as PNG x2 ensures better image quality, but it also doubles physical size (WxL)).

To add or replace an image within the markdown file:

1. Drag the exported image file into the img folder for the component. If you are replacing an existing image, click “Replace” when the pop up comes up.
2. In the markdown file for the component, type in the following HTML tag where you want to add the picture (make sure to edit the filename, accessibility text, and width for each of your images):

<img src="./img/filename.png" alt="accessibility text describing the image" width="width of the sketch artboard"/>

For example, if you want to add an image called “alert-types.png”, you image tag might look like this:

Step 9: Stage and commit changes

Once you’re finished making changes, stage them in Visual Studio Code:

1. When you've completed all changes, click on the numbered bubble in the toolbar’s code icon.

2. In the Changes tab, right-click and select Stage all changes.

3. Return to your terminal application to commit the changes:

   a. Type git status and press Enter. This should list the same files that were listed in your “changes” tab in VSC. If there aren’t any errors, continue to the next step.

   b. Type git commit -m ‘title of your PR’ and press Enter. For example, if you are creating a PR to make edits to the table component design guidelines, you could tupe git commit -m 'changes to table guidelines'. You can edit this title later in GitHub if necessary, but it must be placed between single quote marks ( ‘ ) for now. Be sure to type these single quote marks—copy/pasting them from this page won’t register correctly.

   If this is your first time creating a PR, you may get one of two error messages when submitting this command:

   1. First possibility: Author identity unknown
   
   • To solve this, type: git config --global user.email “you@example.com” , and press Enter. Replace you@example.com with the email you used to create your GitHub account.
   • Then type `git config --global user.name “Your name” , and press Enter. Replace your name with your GitHub username.
   2. Second possibility: fatal: unable to auto-detect email address (got ‘_____’). Do not panic, this just means you need to log into your GitHub account within the terminal. IMPORTANT! You will not be able to log in using your regular github password. You will need to create a personal access token for the password portion of the login. To do this, follow these token instructions.
   • For step 7 of the instructions, set it to never expire
   • For step 8 of these instructions, check all the fields.
   • Once you have your personal access token code, type in your Username in the username field inside the terminal, and type in the token in the password field. WARNING! The password field will not show anything while you type, so make sure you are careful/paying attention. Just because nothing is showing up does not mean it did not go through.

4. Once you get the issue sorted, type in the command that initially gave you the failure/issue again, and then continue to the next step.

5. Type git push origin --set-upstream [name of your branch] and press Enter. For example git push origin --set-upstream iss1234

Step 10: Create a pull request

On GitHub, create a pull request to submit your changes:

1. Go to the patternfly-org repo pulls and click Compare & pull request.

2. On the resulting page, make sure that the arrow points towards the base repository and away from the head repository.

3. Change your PR title if you need to, to describe what the issue was.
4. Leave a comment/description with the words “closes #issuenumber”. For example, if the design doc issue you’re addressing is issue 1234, you would comment “closes #1234”. When you type in the number, the list of issues should pop up - so you can just click the issue from there! Doing this automatically close the original design doc issue when the PR is merged.
5. If you added/edited images, attach all of your image files to this PR so that they can be updated in the original document, merged back into the main branch, and uploaded back to Sketch Cloud for future access.
6. Tag mmenestr to initiate a final review.
7. Submit the PR.

Once you submit your PR, a preview link will be generated by patternfly-build after all checks have passed. If you want, you can use this link to view/review your changes in context, on PatternFly’s.

Step 11: Making updates to an existing/created PR

Now that you’ve created your PR, and have it up for review, your reviewer will take a look at your PR and either:

1. Approve it, and merge it if everything looks good. If this is your case, then congrats! You’re done!
2. Leave comments on it for you to address. If this is your case, you will have to go back into Visual Studio Code (VSC) and edit your PR. You can find the comments on the main PR page, if you scroll down.

How to update a PR

If you have quit your terminal since creating the PR:

• Follow Step 6 again
• Make your edits
• Follow Step 9 again to stage and commit the changes to the existing PR.
• Once you commit and push your changes, a new line will appear in your PR page, showing that you’ve pushed something new/made changes to your PR. (You will not see a green button again to “create a pull request” since you’ve already created one. You are simply adding to an existing one in this case.)
• Ping your reviewer again to let them know that you’ve made updates and that they should do another review.

If you have not quit your terminal since creating the PR:

• Pull up VSC
• Make sure you are on the right branch (git checkout [branchname])
• Make your edits
• Follow Step 9 again to push the changes to the PR.
• Once you commit and push your changes, a new line will appear in your PR page, showing that you’ve pushed something new/made changes to your PR. (You will not see a green button again to “create a pull request” since you’ve already created one. You are simply adding to an existing one in this case.)
• Ping your reviewer again to let them know that you’ve made updates and that they should do another review.

Other useful information

If your PR has merge conflicts in GitHub:

1. Return to your terminal and type git fetch upstream and press Enter.
2. Type git rebase upstream/main and ress Enter.
3. Solve the merge conflicts.
4. Type git add -A and press Enter.
5. Type git rebase --continue and press Enter.
6. Type git push --force origin <name of your branch> and press Enter.

7. Upon merging the pull request, new content will become live on the website in the next release.