Contribution guide

Note: This guide is primarily intended to instruct designers on proper GitHub usage.

Related docs: First-time setup for contributors & Guidelines for PatternFly.org content

Terms: PR—Pull request

Table of contents

• Step 1—Creating a branch for your PR
  • 1.1—Sync your local main branch
  • 1.2—Creating your PR branch
• Step 2—Creating and editing files
• Step 3—Staging and committing changes
  • 3.1—Staging changes
  • 3.2—Committing changes
  • Note—Potential errors
  • 3.3—Pushing changes
• Step 4—Creating your PR
  • 4.1—Creating a PR in GitHub
  • 4.2—PR review process
• Get help

---

Step 1—Creating a branch for your PR

All of PatternFly.org’s current content lives in the “main” PatternFly branch.

This branch is the source of truth that contains all published on PatternFly.org. When you create a PR, you will need to create your own branch, off of the main branch. This is you will be able to make your edits. When you create a pull request, you are essentially asking the system to pull the content you created from your branch into “main”.

1.1—Sync your local main branch

1. In VS Cod, open the patternfly-org folder that you created in your setup process.

2. Open a new terminal within VS Code:

   

3. In your terminal (should open at the bottom of VS Code), enter these commands to make sure you have the latest version of the main branch:

   1. Type git status and press Enter to display the branch you are on.
   2. If you’re not on branch main, type git checkout main and press Enter.
      • Note: that you can type git status at any point to figure out where you are.
   3. Once you’re on the main branch, type git fetch upstream and press Enter to retrieve the latest changes from PatternFly.org.
   4. Type git merge upstream/main to merge the latest changes to your local branch.
   5. Type git push and press Enter to complete the merge.

   The complete process will resemble this:

   

Note—Errors when pushing

1. Sign-in error

   It's possible that you'll get the following popup after typing git push.

   

   If so,

   1. Click Allow.

   2. Click Authorize Visual-Studio-Code if/when prompted.

      

2. Request for password

   You could also get the following prompt: Username for https://github.com:

   1. Type in your GitHub username, then press Enter.
   2. DO NOT type in your regular GitHub account password. Instead, create a token by following GitHub's instructions.
      • At step 7, set it to never expire.
      • At step 8, check all the fields.
   3. Once you have your personal access token code, copy it and paste it in the VS Code terminal and press Enter.
      • Note: For security reasons, the terminal's password field will not show characters as you enter the token, but it is still working.

1.2—Creating your PR branch

Once your main branch is updated, you can create a new PR branch for the issue you're working on.

1. Type git checkout -b [name of your branch] and press Enter.
   • Example: If you’re working on GitHub issue 2020, you would type git checkout -b iss2020.
2. Continue to step 2 to make changes on your PR branch.

---

Step 2—Creating and editing files

Whether you're creating new content or making updates to existing content, follow our separate PatternFly.org writing guide.

Your changes should auto save based on your first-time setup. To check that your changes are saving, you can type git status at any point.

---

Step 3—Staging and committing changes

3.1—Staging changes

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

1. Click on the numbered bubble in the left toolbar’s code icon.

   

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

   

3.2—Committing changes

1. Go to your terminal at the bottom of VS Code to commit the changes:
2. 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.
3. Type git commit -m ‘docs(component): PR title’ and press Enter.
   • For example, if you are creating a PR to make edits to the table component design guidelines, you could type git commit -m ‘docs(table): Updates design guidelines’.
   • Make sure to use single quotation marks (‘). You can edit this title later in GitHub if necessary.

Note—Potential errors

If your commit goes through without issue, you can ignore this and continue to the next step.

If this is your first time creating a PR, you may get one of these 2 errors when submitting this command:

1. "Author identity unknown"

   To resolve this:

   1. Type git config --global user.email “[email protected]” , and press Enter. Replace [email protected] with the email you used to create your GitHub account.
   2. Then type git config --global user.name “Your name” , and press Enter. Replace your name with your GitHub username.

2. "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. To resolve this:

   1. Follow the steps in step 1.
   2. Once you get the issue sorted, type in the commit command that initially gave you the failure/issue again and continue to the next step.

3.3—Pushing changes

1. FINAL STEP! Type git push origin [name of your branch] and press Enter.
   • For example git push origin iss1234.

---

Step 4—Creating your PR

4.1—Creating a PR in GitHub

Navigate to GitHub to finish creating your PR.

1. Go to the patternfly-org repo pulls tab and click Compare & pull request in the yellow alert:

   

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 needed.

4. Update the description with the words “Closes #issuenumber”. For example, if you’re addressing issue 1234, you would add “Closes #1234”. When you type in the number, you can select your issue from the popup. Adding this text ensures that your PR will automatically close the original issue in GitHub.

5. Tag edonehoo to initiate a final review.

6. Submit the PR.

   • Once you submit your PR, a preview link will be generated as a comment. This loads your drafted content onto the PatternFly website, for a better visual of the pending changes:

     

4.2—PR review process

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 VS Code and edit your PR. You can find review comments on the main PR page, if you scroll down.

To update your PR based on feedback:

1. Navigate your VS Code terminal to your PR branch by typing git checkout [name of your branch].

   • Not sure what your original branch was? You can find it beneath the title of of your GitHub PR:

     

   • For example, if your branch name is “iss2020”, you would type git checkout iss2020.

2. Edit files in VS Code.

3. Follow step 4 to stage and commit your edits.

4. Once you commit and push your changes, a new line will appear on your PR page, showing that you’ve pushed something new/made changes to your PR.

5. Message or tag your reviewer to let them know that you’ve made updates that are ready for another review.

6. Once your PR is merged, your new content will go live on the website in the next release. Congrats!

---

Get help

Note: If your PR has merge conflicts in GitHub, reach out to Erin Donehoo (edonehoo) for help.

If you have any other questions, reach out to the PatternFly team via the list-patternfly Slack channel.