Contribute Code to Foundation

Add an awesome new feature or update to an existing one? We'd love for you to contribute some code! Our Wishlist contains some of the hot new features we're itching to get into the framework. Whether it's your first time contributing to an open source project or you're a seasoned pro, we've got tons of ways for you leave your stamp on Foundation.


Terminology

  • The community is anyone commenting on issues or opening pull requests. That includes you!
  • A Yetinaut is the core team of Foundation who has write access to the repository.

A select group of our contributors have been dubbed Yetinauts. They have direct write access to the codebase and are on the Foundation team for the development of the framework. Are you interested in making your mark on the Foundation framework? Whether you’re just submitting bugs or helping us write new features, there are many ways to contribute to Foundation.

Fix your pet peeve

If there's something you'd like to fix about Foundation or any of Foundation's supporting ecosystem, there are many opportunities to be involved. To make it easy, we made a Help Wanted tag on GitHub.

Find a bug we've identified as a good fit for new contributors.

There are many facets to Foundation and that opens up opportunities for people form different skill sets to participate. To make it easy, we made a Help Wanted tag on GitHub. We use tags to indicate if the issue is a bug, feature, and the difficulty level of each.

The following table describes the labels we are using on GitHub:

Type Label Description
These are enhancements to an existing component or proposals for a new feature. New features are exciting and fun to develop and can improve Foundation’s usability or performance.
Documentation or basic HTML/CSS issues that are a great place to get started.
Your skills are coming up and you’re ready to push them further. These involve Sass issue debugging, adding or changing Sass variables, and minor JS bug fixes.
You might be looking for a challenge. These issues are great for someone who can be the hero and push a challenge across the line. This could involve advanced Sass fixes or enhancements, workflow updates in Gulp or the ZURB Stack, and trickier JS bug fixes.

Don't fret - If you’re not sure on the approach to take with specific issue, ask us on the issue and we’ll guide you along.


Find something to work on

If you're interested in contributing to Foundation beyond bug fixing, here's a list of things we'd like to see done to give Foundation for Sites a wider reach, or make it easier to use.

Framework Component Help Wanted

  • Typography: Vertical rhythm
  • Drilldown: Dynamic height
  • Tabs: Deep linking
  • Tabs: Hash support
  • Media queries: Orientation check
  • Sticky: Handle short pages
  • Sticky: Define when sticking starts
  • Dropdown: Fine-tuned alignment
  • Dropdown: Vertical rhythm
  • Dropdown: Prevent auto-resizing
  • Reveal: Back button
  • Interchange: bandwidth detection

Contribute to the Foundation ecosystem.

If you’ve written or ported a package, plugin, tools, Yeoman Generators and more that you think others would benefit from, consider publishing it to the community. The collective hi-five of the internet can be yours if you publish a package that many people find valuable. Blog posts, learning resources, translations, and open-source code are also very welcome; you can get feedback and share your work by tweeting it out with @zurbfoundtion or posting to the Foundation forum.

Wishlist

If you're interested in contributing to Foundation beyond bug fixing, we put together a list of things we'd like to see done to give Foundation for Sites a wider reach, or make it easier to use.

Below are features we’d really like to see in the Foundation ecosystem. This list is not prioritized. We very much welcome contributions that implement any of these things.

  • UMD Support
  • Joyride as a standalone plugin
  • Clearing as a standalone plugin
  • Yeoman generator for ZURB Stack
  • Visual Studio template
  • Polymer components for Foundation
  • Angular 2 version of Foundation plugins
  • Migration from Bootstrap guide

You can find the Foundation for Sites roadmap on GitHub.


Pull requests are always welcome

The most common code contribution is to submit a pull request on GitHub. All you need is a GitHub account! If you solved an issue in your project, share with everyone else!

How to submit a pull request

Foundation is the result of thousands — tens of thousands — of gradual improvements. It wouldn’t be the product it is now without input from our many contributors. And while contributions can improve any open source product, some changes are more helpful than others. Here’s how to make a successful contribution, or pull request, to an open source product — and be part of something great.

We accept tweaks to code and ideas in general through GitHub. This version control service lets us track changes to Foundation — well, any project we do — to keep many developers from accidentally overwriting each other’s work.

What is a pull request?

Pull Requests are changes you make to a copy — not the original — of a project. Once made, you can submit your changes to be reviewed by the project’s owners. If your changes are approved, the project’s owners will "merge" them into the project itself.

That approval process is crucial. When you make a change to a Git repository, pull requests tell people what you did and when. Far from a “big brother” situation, pull requests help everyone understand what happened at a given time to discover, “aha, yesterday’s change affected what I’m trying to do now.”

There are plenty of good guides about the technical aspects of making a pull request. Next we'll talk about what makes a good one.

Making a change

Take Foundation, for example. The process of making a pull request is:

1. Fork a copy of Foundation from GitHub.

A “fork” is a copy of the project in your GitHub account. The system will ask which account, if you have several. For our purposes, your personal account will do. Don’t worry if you accidentally fork a project to the wrong account, or want to remove it later. Deleting a fork can’t hurt the original.

2. Clone the fork.

That’s a fancy way of saying “download the copy to your computer.” While you can make changes to files directly in GitHub, it’s often easier to make changes with your favorite code editor.

3. Make your change to the cloned copy.

We recommend only one change per commit — that is, one descriptive summary of each change. We’ll cover that in a minute.

It's best to create a branch for your your change or fix. Use one branch per issue or feature. Commit your changes — push them back to the repo for review. (For more about setting up Git, checkout the official instructions.)


Boosting your chances: What makes a great PR

When you submit a pull request to a project, it needs to be thorough and descriptive without going overboard. You need to describe your intent as well as your code changes. That’s not always easy to do.

A good title matters.

The title needs to be descriptive of the component being updated and what is being changed. It's a title, so writing a novel here is also not necessary. The key is, be descriptive enough that anyone reading the title will have a surface level understanding of what is happening.

Good “Vertically centers left-right dropdown arrows”
Good “Changes the button to open a new modal window to keep users on the same page.”
Good “Make Tabs' active class names configurable.”
Good “Add (flex-)grid-row size modifier”
Not so good “focus state and input-transition”
Not so good “Link description.”
Not so good “Fix for #8409”

Reference an open issue

If an open issue exists that relates directly to the Pull Request you are submitting, you should reference it. This can be done in the title or in the description of the Pull Request. It helps bring clarity to the purpose or use case you are solving for and will speed up the acceptance of it.

Issues have a number assigned to them. If you paste in the link to the related issue or the number, GitHub will link the two together. Not only does this enhance your description, but it can also automatically close the issue you referenced and post an update on it.

    The following keywords will close an issue via reference in your pull request:
  • close
  • closes
  • closed
  • fix
  • fixes
  • fixed
  • resolve
  • resolves
  • resolved
Example:
This PR closes #9060 by adding role="tablist" to Tab <ul> containers, as documented in the WAI-ARIA Authoring Practice for Tab Panels

Include samples, if possible.

A line of actual code is worth ten lines of description. Give or take.

Describe how to reproduce the problem.

Being able to break down the problem and test solutions is vital to getting something fixed without making the problem worse.

Tell where the problem exists.

In Foundation's case, that means naming the troubled component.

Don't commit many files with only one description.

Dozens of files with changes are difficult to decipher — and describe — in a single pull request.

Each request should be relatively small and focussed. It's better to tackle specific changes in multiple Pull Requests rather than one large one spanning many different components. That way if the project’s owner has to undo the change — a process called “rolling back” — they don’t have to completely wipe out every change you made.

Examples of helpful PR’s

The following are some of the issues in our repo that show how issues should be addressed and closed down:

Code Standards

A good PR is one that follows our coding standards. We want the codebase to use consisent naming, class structure, and syntax.

You can find Foundation's coding standards in our Code Standards repo on GitHub.

What happens when I submit a Pull Request?

Awesome! Simply put, when you submit a PR to Foundation, a team member will review the change and, if it’s valid, merge it into the main branch.

Merging a pull request requires testing. A member of the core Foundation Team or Yetinaut will test the component to ensure the Pull Request solves the issue and ensure there is no regression. This is why describing the steps to reproduce the bug is crucial.

One way to help Pull Requests to get merged faster is to help test them. Especially if you face the same challenge in your project, checking out the Pull Request to confirm it fixes the issue really goes a long way to getting Pull Requests merged.

A member of the core Foundation Team or Yetinaut may ask questions, provide feedback, or reject the pull request with a reason. Foundation is very open to Pull Requests so you may see get suggestions or guidance to modify your Pull Request to get it ready for merging.

Once your Pull Request is merged, GitHub will notify you. Congrats, you just helped thousands of people and contributed to Open Source! We'll be sure to give a shoutout because you are awesome!

Branches matter: Understanding Foundation's project structure.

Foundation uses a specific workflow for managing code updates. This dictates where Pull Requests and code updates should go. It helps make sure that updated code is tested in one place for incrimental releases while providing a place for new features.

Develop
This is the default branch of Foundation and where bugs are squashed. This is also where github will target a PR "by default". For each minior release, the Develop branch is tested, then merged into Master. All bug fixes should be directed to the Develop branch.
Master
The main branch where code updates are deployed (set live) from. Updates to documentation that do not affect the code of Foundation should be pointed to the Master branch.
v6.3
This is the next major release of Foundation. All new features, new components, and enhancements should be directed to the next major release branch (currently v6.3 for Foundation for Sites and v2.3 for Emails)

Reporting issues

Find a confirmed bug? Open an issue for any problem you have with the framework. If there's anything missing from your issue, such as extra context, a code sample, etc., a team member will ask for more info in the comments.

Log it on GitHub so someone has a chance to fix it. If you see an issue with a solution on the Forum, comment and link them together. This will surely help thousands of others over time.

You can also log an issue, or modify the documentation from the documentation pages themselves.

  • Edit this Page: Opens up the page in GitHub and allows you to edit the documentation page. When you submit the changes, it creates a Pull Request on the Master branch.
  • Report a Bug: Takes you to the issue creation in GitHub.

Support requests are generally better suited for the Foundation Forum, while GitHub is more appropriate for bugs. If you aren’t sure if your issue is a bug or not, don’t worry! Post your problem on GitHub and the team will help you along. Every participant is expected to follow the project's Code of Conduct so please be courteous and respectful.

We’re looking forward to seeing you participate in the Foundation community!

Rafi & The Foundation Team