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

(scroll down for detailed instructions)

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

If you are comfortable with this process and want to work on multiple features simultaneously, Learn about Multiple Branches here.

Detailed instructions for a single contribution:

Follow these detailed guidelines, of the 5 basic steps, to learn how to submit a contribution.

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 to the site

Pages are posted to the site using a site.md file. 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 contains the location or 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 masthead pattern, where the location or path is specified:

---		
layout: page-pattern		
overview: pattern-library/application-framework/masthead/design/overview.md		
design: pattern-library/application-framework/masthead/design/design.md		
code: false		
---		

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 you have code samples for your design, the Code attribute in the site.md file, should be changed from code: false to `code: true' and add the following optional headers:

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

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. These implementations can be linked-to, from the design/status page, to show that the pattern has been implemented for a particular framework integration.
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: ...		
impl_css: ...		
---