Third-party patches are essential for keeping open-source software great. In the spirit of keeping it as simple as possible to contribute changes that get things working in your environment, here are a few guidelines that contributors should follow. As Nicholas Gallagher put it in his contributing guidelines:
Following these guidelines helps to communicate that you respect the time of the developers managing and developing […]. In return, they should reciprocate that respect in addressing your issue or assessing your patches and features.
- Get Started
- Create an Issue
- Create a Feature Request
- Contribute Documentation
- Create a Pull Request
- Join the team
- Additional Resources
- Make sure you have a GitHub account.
- Please ask the CODEOWNERS before making significant changes. I'd hate for you to put in a lot of work for something that doesn't align with the vision of this project.
- Search on Github within the repo for the issue or Pull Request. This means you have to read through the issue(s) in order to determine if your particular issue has already been created. Don't forget to look through the closed ones as well.
- If the issue has not been fixed then try to reproduce the issue in a fresh clone of the repository off the master branch. Read below on how to set up your environment.
- Create a reduced test case as outlined by Chris Coyier of CSS Tricks. Link to the Code Pen, JS Bin, or whatever you use, as long as its publicly accessible.
- Read our branching strategy, commit conventions below for tips on how to contribute. We won't accept any pull request that doesn't adhere, so be forewarned.
If this seems like a lot or you aren't able to do all this setup, you might also be able to edit the files directly without having to do any of this setup. Yes, even code.
The easiest way to contribute is to help improve the library by finding bugs within the system. Bugs are small, testable and demonstrate problems caused by the code. A good report will be able to easily outline the problem and provide steps to recreate. If you're going to submit a bug, please verify you've done everything on the list above. Don't be afraid to go into detail; no one ever said too much detail was a problem, and if they did, it wasn't us.
Now its time to submit a ticket. Bug reports should be thorough and not leave anyone wondering or questioning what you were thinking. No one should have to ask you anything or require further clarification. When creating a ticket, use the Bug Report template to populate a lot of the information required. Below is a brief description of the parts of a bug report:
- title (required): should be concise and descriptive. Anyone should be able to know what you're issue is at a glance and doesn't need the complete issue in it; try to keep it under 80 characters.
- description: create a short summary of what is happening or what you're seeing.
- to reproduce (required): the steps you followed to find this bug. This will make life so much easier to help fix the issue. Don't make any assumptions that someone will be on the same page or do the same thing as you. Nice and direct steps of what happened, what you clicked on can ease the time for us to debug.
- expected behavior (required): let us know what you were expecting to happen. This may or may not align with the project, so be very detailed with this part; the more detail the better.
- screenshots: a picture is worth a thousand words.
- device details (required): for most of the information you can look at https://www.whatsmybrowser.org; for others check out below for how to find them.
- OS & version: Always include the OS(es) and version(s) where you found the issue. If, for example its Mavericks, you can put OSX 10.9.1.
- Browser(s) Version(s): Which browsers have you tested this in? What version are you running?
- Node Version(s): Not always required, but if there is something erring in the console, this is quite helpful.
- NPM Version(s): Not always required, but if there is something erring in the console, this is quite helpful.
- Browser Resolution: Include resolutions as more of a range rather than an absolute. For example, < 768px or >= 768px && <= 1024th
- Library Version: Required; please include which version of this library you're using
Follow the example below and you'll be on the right path. Let's assume that a you're trying build a new page on your application and the icons aren't showing up:
Title: Icons are not showing up
**Describe the bug**
Developing my application and when it loads up
the browser, I don't see any of the SVG icons loading up.
**To Reproduce**
1. Open http://example.com/new-app
2. There is a blue button in the right side of the toolbar that says "Edit"
3. Notice there should be a pencil icon, and there is nothing.
**Expected Behavior**
When loading any page that contains an icon, I expect the icon to load alongside
the other assets on the page, ie text, components, modules, etc
**OS**: OSX 10.8.3
**Browser(s) Version(s)**: All browsers, but founded initially in Chrome 38.0.2125.111
**Node Version(s)**: v.7.8.0
**NPM Version(s)**: 4.2.0
**Browser Resolution(s)**: initially found at 1920 x 2063, but appears >768
**Library Version**: 2.15.5
**Additional context**
- **Results**: Passed
- **Line(s) of Code**: n/a
- **Message**: n/a
- **Console Errors**: 404 error on "svg/symbol-defs.svg"It's helpful, but not required to run the test suite locally. If you have the time and energy it can increase the efficiency and decrease the effort required for us to fix things.
There are 2 sides to test, CSS and JS. For the CSS, you can can run npm run lint:css to check for syntax errors that may cause issues, or you can run npm run test:css to test the mixins and/or CSS. With regard to JS, the same applies; run npm run lint:js to check syntax errors and npm run test:js to test the JS components. You can also run linting and testing on both sides by running npm run lint and npm test respectively.
- Results: If there is a fail in a particular test, include the name of the test, otherwise list as "Passed".
- Line(s) of Code: Definitely not a requirement, but doesn't hurt if you've already pin pointed the issue.
- Message: When the tests fail, a stack trace or message is typically output, so copy/paste that into the issue.
Now that you've created an issue, maybe you want to try your hand at fixing the issue? Set up your environment.
Another way to contribute is to help improve the library by suggesting new ideas within the system. While we may not accept every feature, it doesn't hurt to suggest improvements, but please stop and think about the intent of the project. Maybe its better in another independent project, or maybe not; there is no harm in asking, or filling out a feature request. Before you do submit, please look at my road map to see if I've already thought of your feature. And remember, if I don't like the idea, doesn't mean you can't fork the project.
Now its time to submit a ticket. Feature requests should be thorough and not leave anyone wondering or questioning what you were thinking. No one should have to ask you anything or require further clarification. When creating a ticket, use the Feature Request template to populate a lot of the information required. Below is a brief description of the parts of a feature request:
- Is your feature request related to a problem?: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
- Describe the solution you'd like: A clear and concise description of what you want to happen. Acceptance criteria are important for us to ensure a proper and complete feature.
- Describe alternatives you've considered: A clear and concise description of any alternative solutions or features you've considered.
- Additional context: Add any other context or screenshots about the feature request here.
Follow the example below and you'll be on the right path.
Title: Progress bar component
**Is your feature request related to a problem? Please describe.**
Not related to a problem. I would like to see an indicator of impressions to ad requests
so that I can visualize the loss.
**Describe the solution you'd like**
I think a progress bar where the total value shown is the full width of
the contained area, and the part that is filled in is the impressions.
**Describe alternatives you've considered**
A funnel chart was considered but its too similar to Googles design and
Legal fears repercussions.
**Additional context**
N/ADocumentation is a super important, critical part of this project. Docs are how we keep track of the what, how, and why of we're doing; it's how we stay on the same page about our policies. And it's how we tell others everything they need in order to be able to use this project -- or contribute to it. So thank you in advance.
Contributions of any size are welcome! Feel free to file a PR even if you're just rewording a sentence to be more clear, or fixing a spelling mistake!
To contribute:
- Set up the project.
- Edit or add any relevant documentation.
- Make sure your changes are formatted correctly and consistently with the rest of the documentation.
- Re-read what you wrote, and run a spellchecker on it to make sure you didn't miss anything. Check out Grammerly for spelling and grammar mistakes as well as tone of writing.
- In your commit message(s), begin the first line with
chore(docs):. For example:chore(docs): Adding a doc contrib section to CONTRIBUTING.md. - Write clear, concise commit message(s) using the convention described below. Documentation commits should use
chore(docs): <message>. - Go to <https://github.com/the-holocron//pulls> and open a new pull request with your changes and fill out the template with the appropriate information.
- If your PR is connected to an open issue, add a line in your PR's description that says
Fixes: #123, where#123is the number of the issue you're fixing.
Once you've filed the PR:
- One or more maintainers will use GitHub's review feature to review your PR.
- If the maintainer asks for any changes, edit your changes, push, and ask for another review.
- If the maintainer decides to pass on your PR, they will thank you for the contribution and explain why they won't be accepting the changes. That's ok! We still really appreciate you taking the time to do it, and we don't take that lightly.
- If your PR gets accepted, it will be marked as such with the
next-releaselabel, and merged soon after. Your contribution will be distributed to the masses next time the maintainers tag a release
If you're unfamiliar with the Github flow, please read this guide as an introduction. Make sure you reach out to someone on the team before you start any work to ensure that what you're doing is aligned with the teams' vision. Read Ilya Grigorik's great article Don't "Push" Your Pull Requests. The following passage sums up some great points:
Contributions are always welcome, but surprise patches are mostly just a burden. Yes, you are offering your help, but someone else will have to maintain your code over the long term - get their buy-in first, avoid surprises. Even worse, a localized change to address a specific problem will often miss the full implications to the project: other existing use cases, future roadmap plans, or overall architectural decisions. A good idea can be implemented inappropriately for the specific project; it can be invalidated by another effort that you may not even be aware of; the timing may be wrong, and a dozen other reasons can conspire against you.
IMPORTANT: By submitting a patch, you agree to the same license as that used by the project.
For those of you willing to help out, that's great!!! Here's a quick how-to with regarding to submitting your changes to Github. This requires no need for access, rights or privileges and can be done without any help from a team member.
- Fork It by pressing the "Fork" button in the top right corner.
- Clone your newly forked repo (
git clone https://github.com/<github-user>/<repo>). - Change into the directory you cloned (
cd <repo>) - Add your fork as a remote (
git remote add <github-user> https://github.com/<github-user>/<repo>) where<github-user>is your actual Github username and<repo>is the repository with which you're looking to contribute. - Create your feature branch (
git checkout -b <my-new-feature>); checkout the guide below for our branching strategy - Commit your changes (
git commit), following the format suggested below. Please don't use the shortcut flaggit commit -m <message>as there is more detail required than what is allowed by only using that flag. - Push to the branch (
git push <github-user> <my-new-feature>) - Create a new Pull Request; make sure you fill in the Pull Request template. a. Most of the time the Reviewers sections provides suggestions and you should include them; in cases when it doesn't add the core team. b. Don't forget to update the CODEOWNERS file adding the directory and your name to the end of the list.
IMPORTANT: Every patch and subsequent message should have a bug attached. If there is no ticket, no work should be done.
- Please avoid working directly on the
masterbranch. - Make commits of logical units.
- Check for unnecessary whitespace with
git diff --checkbefore committing. - Make sure your commit messages are in the proper format, also listed below in our guides.
ALL WORK REQUIRES A BRANCH. WE DO NOT PUSH DIRECTLY TO MASTER!
There are a lot of various opinions on branching strategies and while all of them are great and have their place, they all tend to add a lot of overhead and maintenance with little value to the workflow. We prefer to use the simplified strategy known as Github flow. So when working with the library, there's no need to prefix it with feature/ or hotfix/ or anything like that; Github's PR-style workflow allows for quick and disposable branches. Create branches off master and use descriptive names such as create-donut-chart, refactor-dropdown so that users can easily see what's being worked on.
Branch names should short, concise and easy to understand the work that is being done. While not a necessity, setting up <tab> completion for git branches can speed up the discovery of branch names. The following tips are designed to speed up your workflow with the addition of tab completion.
- Use only lower case letters. Lowercasing makes it quicker to type by providing fewer letters to get working. Avoid upper case letters as it requires a higher level of dexterity that can decrease the speed of workflow
- Use dashes instead of underscores. The same is true as above, they're are easier to type and require less dexterity.
- Don't prefix the branch name with any particular pattern. Unless you regularly clean up your local branches, it's likely to increase the number of characters and tabbing through in order to complete the branch name you seek
- Don't include the ticket number. Adding it falls into the same faults as suggestion 2 above; it requires a lot more typing in order to tab complete through to the branch you may want
When searching through a bunch of branches, issue-123 doesn't provide any inherent value to the developer in hopes to find the feature they want to help out on; however seeing modal-trigger-open gives the developer some insight into what work is being done.
// good
git checkout -b fix-bug-x
git checkout -b new-component
// bad
git checkout -b JIRA_1234
git checkout -b tests
The only exception, at the time of this writing, is for tagging and releasing
If you're contributing to the codebase, its helpful to know the handful of commands that are used to ensure code is of the highest quality or allows you to visual your changes. Below is the list of tasks available:
These tasks are run most often, and most are required to pass checks before any feature can be approved.
| Command | Description | Notes |
|---|---|---|
npm run dist |
Runs babel and/or sass compliers to convert (S)CSS and JS(X) to browser-friendly code |
No reason to run this unless you're debugging output of code. This is run as part of the publishing process, so ensuring it passes can help. |
npm run lint |
Runs the linting suite; includes markdown, (S)CSS, and JavaScript | Husky will attempt to run this on every commit and auto-fix. While it's not required for this to pass and you may bypass with the flag of --no-verify, its good to run to help debugging and ensure a faster PR process. |
npm test |
Runs the testing suite; includes sensitive language, (S)CSS, and JavaScript | If the test coverage drops below the configured numbers, this will fail despite all tests pass. In that event, you should see a message with the percentages to which it dropped. |
npm start |
Runs storybook to test component development |
Make sure all variations are covered and all props have knobs |
Not the main tasks that get run everyday, but in the event you need finer control or help, these are available.
| Command | Description | Notes |
|---|---|---|
npm run commit |
Runs the interactive commitlint for help contributing an acceptable commit message |
https://commitlint.js.org |
npm run dist:css |
Runs sass and postcss to compile the (S)CSS into CSS |
https://sass-lang.com, https://postcss.org |
npm run dist:js |
Runs babel to compile the JS(X) into JS; check out the config |
https://babeljs.io |
npm run lint:css |
Runs stylelint to test the (S)CSS for style violations; check out the rules |
https://stylelint.io |
npm run lint:js |
Runs eslint to test the JS(X) for style violations; check out the rules |
https://eslint.org |
npm run test:docs |
Runs alex to test for sensitive language |
https://alexjs.com |
npm run test:js |
Runs jest for testing on (S)CSS mixins, and JavaScript; check out the config |
https://jestjs.io |
npm run docs |
Runs storybook to build out the docs/; check out the config |
https://storybook.js.org |
Commits should be small, concise and logical units of code. The goal is not to overwhelm reviewers with superfluous changes; do not add any unrelated changes to a commit in case the change needs to be reverted or backed out. The entirety of your code should answer the question:
Which problem am I trying to solve today?
All changes should be connected and without 1 change your entire commit would fall apart. If you find that you can keep a commit out and your code still makes sense, runs successfully, and fixes an issue then you're likely in a good condition to commit some code and create a pull request. Contributors are required to follow the Conventional Commits specification on all commit messages. If you're ready, follow below to create a good commit message in the proper format.
A few tips to consider:
- Absolutely no working directly on the master branch!!!
- Check for unnecessary whitespace with
git diff --checkbefore committing. - And be sure to run git commit and NOT
git commit -m <message>so that you can fill out the body of the message
A commit should consist of a required title, optional but recommended body and an optional but recommended footer. Below is the desired format with an example:
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
fix(filter): patch Autocomplete output when query is empty
Show default options when no Autocomplete search input value is present.
Fixes #1234
- The first line should be less than 50 characters (our git-hooks will warn about this) but no greater than 72.
- The and should always be lowercase as shown in example.
- is required
- is optional
- should be written in the imperative with present tense.
- Should contain no full stop (.).
- feat (new feature for the user, not a new feature for build script)
- fix (bug fix for the user, not a fix to a build script)
- chore (updating tasks etc, changes to docs, linting warnings, adding tests; no production code change)
should indicate the feature, component, or part that is being fixed. It should be very short but obvious.
The value can be omitted. The feature may not exist or be too complex to assign to a single component. If the is empty the parenthesis should not be added to the title.
- optional, thorough descriptions are helpful for understanding commits
- wrap it to about 72 characters or so
- uses the imperative, present tense: “change” not “changed” nor “changes”; this convention matches up with commit messages generated by commands like git merge and git revert
- includes motivation for the change and contrasts with previous behavior
- it's more important that you include why these changes were made then listing out what was done
- must be separated by a blank line from title
- in some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together.
- further paragraphs come after blank lines.
- bullet points are okay, too
- typically a hyphen or asterisk is used for the bullet, followed by a single space, with blank lines in between, but conventions vary here
- use a hanging indent
- optional
- can reference which task it covers
- can cover breaking changes
- must be separated by a blank line
Code Owners is a powerful way to define individuals or teams that are responsible for code in a repository. When updating any bug or feature, be sure to update this file to include yourself for potential future reviews.
Code owners are automatically requested for review when someone opens a pull request that modifies code that they own. Code owners are not automatically requested to review draft pull requests.
When someone with admin or owner permissions has enabled required reviews, they also can optionally require approval from a code owner before the author can merge a pull request in the repository.
All teams are required to add the file within the .github/ directory on the root of the repository. The format is the same as .gitignore which is followed by one or more GitHub usernames or team names using the standard @username or @org/team-name format. You can also refer to a user by an email address that has been added to their GitHub account, for example user@example.com.
# This is a comment.
# Each line is a file pattern followed by one or more owners.
# These owners will be the default owners for everything in
# the repo. Unless a later match takes precedence.
# Typically the owners team should be responsible for the
# entire repository.
* @org/team
# Order is important; the last matching pattern takes the most
# precedence. When someone opens a pull request that only
# modifies JS files, only maintainers and not the global
# owner(s) will be requested for a review.
*.js @org/maintainers
# You can even call out other teams for audits.
# In this example, @org/design owns any file in an that ends in
# .scss or .css anywhere in your repository. Typically
# all CODEOWNERS should have their (S)CSS audited by the UX
# design team.
*.scss @org/design
*.css @org/design
As you can see from the example above, it automates the need to ask developers to review code. Even further, we can use GitHub's branch protection to ensure that code isn't pushed through if the code owner(s) aren't consulted. The other side effect is providing outside contributors the knowledge of knowing whom to ask when looking to fix or improve library code. One should always reach out to someone on the team before making significant changes. We'd hate for you to put in a lot of work for something that doesn't align with the vision of this project.
There are many ways to contribute! Most of them don't require any official status unless otherwise noted. That said, there's a couple of positions that grant special repository abilities, and this section describes how they're granted and what they do.
All of the below positions are granted based on the project team's needs, as well as their consensus opinion about the persons desire to help. The process is relatively informal, and it's likely that people who express interest in participating can be granted the permissions they'd like.
You can spot a collaborator on the repo by looking at the teams.
Below is a table of various permission levels each member may have and what that may grant them.
| Permission | Description |
|---|---|
| Contributor | Granted to contributors who express a strong interest in spending time on the project's issue tracker. These tasks are mainly labeling issues, cleaning up old ones, and reviewing pull requests, as well as all the usual things non-team-member contributors can do. Maintainers should not merge pull requests, tag releases, or directly commit code themselves: that should still be done through the usual pull request process. Becoming a Maintainer means the project team trusts you to understand enough of the team's process and context to implement it on the issue tracker. |
| Maintainer | Granted to contributors who want to handle the actual pull request merges, tagging new versions, etc. Maintainers should have a good level of familiarity with the codebase, and enough context to understand the implications of various changes, as well as a good sense of the will and expectations of the project team. |
| Owner | Granted to people ultimately responsible for the project, its community, etc. |