How to Submit a Contribution

Let's get started!

Making a single PatternFly contribution

There are 5, basic, ordered steps to remember when making a contribution.

1. Pull
2. Commit
3. Select
4. Push
5. Create Pull Request

A single contribution, is the most straight forward method of contributing, and is a great place to begin, if this is your first time contributing to PatternFly. There are 5 basic steps to a single contribution and to learn how to submit a contribution, scroll down to see the detailed instruction.

Making multiple PatternFly contributions and working on more than one contribution, at a time

If you would like to make multiple PatternFly contributions at one time, we advise using multiple branches. Multiple branches allows you to submit multiple pull requests at a time, keeping contributions organized. Learn about Multiple Branches here.

Single Contribution Detailed Instructions

1. Pull: always start by making sure the you have the latest files to work with.

The first thing you should always do, when contributing a new pattern, or making changes to an existing pattern, is to make sure all of the files you are working with are up to date.

1. Make sure that your local repository is selected, and click the Pull icon, in the toolbar.

1. A modal will pop up. Where it says, Pull from repository, select upstream from the drop down menu.
2. Where it says Remote branch to pull: select master from the drop down menu.
3. Check the box that says Rebase instead of merge

Create or update the pattern

We recommend using Atom to edit .md files. You can reference the GitHub Markdown files for help formatting.

1. On your desktop, use Finder to open up your "patternfly-design" folder.
2. Locate the folder, for the pattern you would like to edit, from the "pattern-design" folder.
   

• If this folder does not exist;
  a. Copy the "pattern-template" folder, located in the "pattern-design" folder
  b. Paste it in a location, within the "pattern-design" folder, that was specified on the GitHub issue, for this pattern.
  c. Rename the folder, as was specified on the GitHub issue, for this pattern.
  

3. Add and edit the relevant files and images, in this folder. Feel free to discard example and placeholder content, in these template files.

Hint: When using the Atom editor, you can view your markdown changes, by navigating the main menu: Packages > Markdown Preview > Toggle Preview.

Folder + File Structure

Files in this repository adhere to the following file structure

├── pattern-library
│   └── {category-name}
│       └── {pattern-name}
│           ├── discovery
│           │   ├── documents
│           │   │   ├── ...
│           │   │   └── ...
│           │   ├── img
│           │   │   ├── {pattern-name}-{variation-name}.png
│           │   │   ├── {pattern-name}-{variation-name}-callout.png
│           │   │   └── ...
│           │   └── discovery.md
│           ├── design
│           │   ├── documents
│           │   │   ├── ...
│           │   │   └── ...
│           │   ├── img
│           │   │   ├── {pattern-name}-{variation-name}.png
│           │   │   ├── {pattern-name}-{variation-name}-callout.png
│           │   │   └── ...
│           │   ├── design.md
│           │   └── overview.md
│           ├── usability-testing
│           │   ├── documents
│           │   │   ├── ...
│           │   │   └── ...
│           │   └── usability-testing.md
│           └── site.md

...

All folder and markdown file names should be in lower case with dashes in place of spaces. Image file names should include the name of the pattern and, if possible, the defining feature of the image. Most importantly, however is that the name is descriptive and not something like "image13copy.png" Source files for all images used in the pattern library should be stored in the "design/documents" folder for the pattern in question. This will allow image files to be updated in the future, if needed.

2. Commit (save) your changes

When you add a new file to your repository or make a change, you need to stage, commit, and push that change to your remote repository.

1. Click on the Commiticon, in the toolbar. Commit is like saving a version of one or more files.
2. The number next to the "file status", indicates the number of changes.

3. Select the changes

1. In the bottom pane of the screen, under "Unstaged", check the boxes next to any changed files that you would like to include, when you commit your files. (selecting the Unstaged files checkbox, will automatically select all files.) Selected files will move from Unstaged files into Staged files.

2. Add a description (usually 55 characters or fewer) of your edits, for the Commit.
3. Click the Commit button, to commit all stages changes.

4. Push your changes

1. Click the Push icon, in the toolbar, to push your committed changes.

This sends your committed changes from your local repo, to the remote patternfly-design repo, so that others may access them.

2. A modal will pop up, where it says Push to repository, make sure origin` is selected, and then select the branch you wish to push from. (the branch where you have made changes).
3. Click the OK button.

4. You should then see that your local and remote (origin) repos are synchronized. The branch you are pushing from and your github github repository (origin/"branch") should be on the same line together, indicating they are in sync.

5. Create a Pull Request (submit your changes to Patternfly)

Whether you are making a change to an existing pattern or adding a new one, you will need to send a pull request (PR) written in markdown to the patternfly-design repo (If you can read this, you're already in the patternfly-design repo!). The PR will be a way for stakeholders to review, discuss, and refine the design with the goal of merging it as PatternFly documentation and making it viewable on patternfly.org. Design documents are living documents, therefore new PRs may be opened to add to or modify the documentation as necessary.

1. In the SourceTree menu bar, Go to Repository > Create Pull Request

2. Ensure that the Submit Via remote field is set to origin and that the other two fields are set to master.

3. Click Create Pull Request on Web. SourceTree will open a browser window on GitHub for you.
4. Click Create a Pull Request, add a comment if relevant.

Posting your contribution to the PatternFly.org website

You can post contributions to the patternfly.org website, by introducing a site.md file. The site.md file will add pages to the website or updated any changes that have been made to an existing site.md file, for a component. The site.md file can be found in the local folder, of the patternfly-design repo, that was created on your desktop, during the set up for contributions.

The site.md file specifies the path of your files in the patternfly-design directory, and is where you identify and provide information, if your pattern also had code.

For example, here is the site.md file for the Aggregate Status Card pattern, where the location or path is specified:

---		
layout: page-pattern		
overview: pattern-library/cards/aggregate-status-card/design/overview.md
design: pattern-library/cards/aggregate-status-card/design/design.md
code_html: code/cards/aggregate-status-card/code.md
code_angular: /components/angular-patternfly/dist/docs/partials/api/patternfly.card.component.pfAggregateStatusCard.html
impl_jquery: https://rawgit.com/patternfly/patternfly/master-dist/dist/tests/cards.html
impl_angular: https://www.patternfly.org/angular-patternfly/#/api/patternfly.card.directive:pfAggregateStatusCard		
---		

If this pattern does NOT have code

For new patterns, without any code samples, the site.md file looks like:

---		
layout: page-pattern		
overview: pattern-library/{category-name}/{pattern-name}/design/overview.md		
design: pattern-library/{category-name}/{pattern-name}/design/design.md		
code: false		
---		

• A design does not have to have code, to be a valid submission. If you do not have code for your design, leave the code attribute set to 'false’.

If this pattern does have code

• If the code for your design has already been introduced to PatternFly, replace “code: false” with the appropriate paths for either or both, “code_html:” and “code_angular”.

code_html: false OR path/to/code.md		
code_angular: false OR /path/to/patternfly.component.html		
url-js-extra: ['path/to/script.js']		
---		

You can find the paths for PatternFly code examples here:

• patternfly-core html
• angular-patternfly

Linking pattern implementations

If your pattern does have code, also include the following attributes for implementation of the pattern, in your site.md file.

Pattern implementations host running examples of their implementation in standalone sites, referred to as showcases. These implementations can be linked-to, from the design/status page, to show that the pattern has been implemented for a particular framework integration.

You can find the showcases with the various PatternFly JS implementations here:

• patternfly-jquery showcase
• angular-patternfly showcase
• patternfly-ng showcase
• patternfly-react showcase
• patternfly-webcomponents showcase

This link is added to the status page by modifying the site.md file for a pattern. By setting the YAML front matter attribute for each of the respective framework integrations, the status page will be updated accordingly:

---		
...		
impl_jquery: https://rawgit.com/patternfly/patternfly/master-dist/dist/tests/...		
impl_angular: https://www.patternfly.org/angular-patternfly/#/api/...		
impl_ng: ...		
impl_react: ...		
impl_webcomponent: ...			
---