Contribution guide

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

---

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. Open VS Code and 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. First, type git status. This will display the branch you are on.
   2. If you’re not on branch main, type git checkout main 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. This fetches the latest changes from the main branch.
   4. Type git merge upstream/main to merge the latest changes to your local branch.
   5. Then type git push to complete the merge.

      1. You could get the following popup after typing git push. If so, click Allow.

         

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

           

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

         • If so, type in your GitHub username, then press Enter.
         • In the following field, 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.
         • Once you have your personal access token code, copy it and paste it in the password field back in the VS Code terminal. Then 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.

   Complete synching example

   Here's what successfully updating your main branch looks like:

   

1.2—Creating your PR branch

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

1. Type git checkout -b [name of your branch] and press Enter.
   • For example, if you’re working on GitHub issue 2020, you would type git checkout -b iss2020, to align your branch name with the issue number.
2. Edit files in VS Code, by referring to Step 7. 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.

1.3—Updating an existing PR branch

If you're working on updating a PR that you've already opened:

1. Navigate your VS Code terminal to the right folder. Follow bullets 1 and 2 of creating a new PR if you need help.

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

     

2. Navigate to the PR branch 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 VS Code. Continue to Step 9 to commit your changes.

---

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.

---

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 you need to, to describe what the issue was.

4. Update the 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. Tag edonehoo to initiate a final review.

6. Submit the PR.

   • Once you submit your PR, a preview link will be generated by patternfly-build after all checks have passed. 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. In VS Code, navigate to your PR branch (git checkout [branchname]) Make your edits
2. Follow the steps to stage and commit your edits.
3. 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.)
4. Ping your reviewer again to let them know that you’ve made updates and that they should do another review.
5. Upon merging the pull request, new content will become live on the website in the next release.

---

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.