1# Contributing to Bootstrap 2 3Looking to contribute something to Bootstrap? **Here's how you can help.** 4 5Please take a moment to review this document in order to make the contribution 6process easy and effective for everyone involved. 7 8Following these guidelines helps to communicate that you respect the time of 9the developers managing and developing this open source project. In return, 10they should reciprocate that respect in addressing your issue or assessing 11patches and features. 12 13 14## Using the issue tracker 15 16The [issue tracker](https://github.com/twbs/bootstrap/issues) is 17the preferred channel for [bug reports](#bug-reports), [features requests](#feature-requests) 18and [submitting pull requests](#pull-requests), but please respect the following 19restrictions: 20 21* Please **do not** use the issue tracker for personal support requests. Stack 22 Overflow ([`twitter-bootstrap-3`](http://stackoverflow.com/questions/tagged/twitter-bootstrap-3) tag) or [IRC](https://github.com/twbs/bootstrap/blob/master/README.md#community) are better places to get help. 23 24* Please **do not** derail or troll issues. Keep the discussion on topic and 25 respect the opinions of others. 26 27* Please **do not** open issues or pull requests regarding the code in 28 [`Normalize`](https://github.com/necolas/normalize.css) (open them in 29 their respective repositories). 30 31 32## Bug reports 33 34A bug is a _demonstrable problem_ that is caused by the code in the repository. 35Good bug reports are extremely helpful, so thanks! 36 37Guidelines for bug reports: 38 391. **Use the GitHub issue search** — check if the issue has already been 40 reported. 41 422. **Check if the issue has been fixed** — try to reproduce it using the 43 latest `master` or development branch in the repository. 44 453. **Isolate the problem** — ideally create a [reduced test 46 case](http://css-tricks.com/6263-reduced-test-cases/) and a live example. 47 [This JS Bin](http://jsbin.com/EBAwOkOK/1) is a helpful template. 48 49 50A good bug report shouldn't leave others needing to chase you up for more 51information. Please try to be as detailed as possible in your report. What is 52your environment? What steps will reproduce the issue? What browser(s) and OS 53experience the problem? Do other browsers show the bug differently? What 54would you expect to be the outcome? All these details will help people to fix 55any potential bugs. 56 57Example: 58 59> Short and descriptive example bug report title 60> 61> A summary of the issue and the browser/OS environment in which it occurs. If 62> suitable, include the steps required to reproduce the bug. 63> 64> 1. This is the first step 65> 2. This is the second step 66> 3. Further steps, etc. 67> 68> `<url>` - a link to the reduced test case 69> 70> Any other information you want to share that is relevant to the issue being 71> reported. This might include the lines of code that you have identified as 72> causing the bug, and potential solutions (and your opinions on their 73> merits). 74 75 76## Feature requests 77 78Feature requests are welcome. But take a moment to find out whether your idea 79fits with the scope and aims of the project. It's up to *you* to make a strong 80case to convince the project's developers of the merits of this feature. Please 81provide as much detail and context as possible. 82 83 84## Pull requests 85 86Good pull requests—patches, improvements, new features—are a fantastic 87help. They should remain focused in scope and avoid containing unrelated 88commits. 89 90**Please ask first** before embarking on any significant pull request (e.g. 91implementing features, refactoring code, porting to a different language), 92otherwise you risk spending a lot of time working on something that the 93project's developers might not want to merge into the project. 94 95Please adhere to the [coding guidelines](#code-guidelines) used throughout the 96project (indentation, accurate comments, etc.) and any other requirements 97(such as test coverage). 98 99Adhering to the following process is the best way to get your work 100included in the project: 101 1021. [Fork](http://help.github.com/fork-a-repo/) the project, clone your fork, 103 and configure the remotes: 104 105 ```bash 106 # Clone your fork of the repo into the current directory 107 git clone https://github.com/<your-username>/bootstrap.git 108 # Navigate to the newly cloned directory 109 cd bootstrap 110 # Assign the original repo to a remote called "upstream" 111 git remote add upstream https://github.com/twbs/bootstrap.git 112 ``` 113 1142. If you cloned a while ago, get the latest changes from upstream: 115 116 ```bash 117 git checkout master 118 git pull upstream master 119 ``` 120 1213. Create a new topic branch (off the main project development branch) to 122 contain your feature, change, or fix: 123 124 ```bash 125 git checkout -b <topic-branch-name> 126 ``` 127 1284. Commit your changes in logical chunks. Please adhere to these [git commit 129 message guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) 130 or your code is unlikely be merged into the main project. Use Git's 131 [interactive rebase](https://help.github.com/articles/interactive-rebase) 132 feature to tidy up your commits before making them public. 133 1345. Locally merge (or rebase) the upstream development branch into your topic branch: 135 136 ```bash 137 git pull [--rebase] upstream master 138 ``` 139 1406. Push your topic branch up to your fork: 141 142 ```bash 143 git push origin <topic-branch-name> 144 ``` 145 1467. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/) 147 with a clear title and description against the `master` branch. 148 149**IMPORTANT**: By submitting a patch, you agree to allow the project owners to 150license your work under the terms of the [MIT License](LICENSE.md). 151 152 153## Code guidelines 154 155### HTML 156 157- Two spaces for indentation, never tabs. 158- Double quotes only, never single quotes. 159- Always use proper indentation. 160- Use tags and elements appropriate for an HTML5 doctype (e.g., self-closing tags). 161- Use CDNs and HTTPS for third-party JS when possible. We don't use protocol-relative URLs in this case because they break when viewing the page locally via `file://`. 162- Use [WAI-ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) attributes in documentation examples to promote accessibility. 163 164### CSS 165 166- CSS changes must be done in `.less` files first, never just in the compiled `.css` files. 167- Adhere to the [CSS property order](http://markdotto.com/2011/11/29/css-property-order/). 168- Multiple-line approach (one property and value per line). 169- Always a space after a property's colon (e.g., `display: block;` and not `display:block;`). 170- End all lines with a semi-colon. 171- For multiple, comma-separated selectors, place each selector on its own line. 172- Attribute selectors, like `input[type="text"]` should always wrap the attribute's value in double quotes, for consistency and safety (see this [blog post on unquoted attribute values](http://mathiasbynens.be/notes/unquoted-attribute-values) that can lead to XSS attacks). 173- Attribute selectors should only be used where absolutely necessary (e.g., form controls) and should be avoided on custom components for performance and explicitness. 174- Series of classes for a component should include a base class (e.g., `.component`) and use the base class as a prefix for modifier and sub-components (e.g., `.component-lg`). 175- Avoid inheritance and over nesting—use single, explicit classes whenever possible. 176- When feasible, default color palettes should comply with [WCAG color contrast guidelines](http://www.w3.org/TR/WCAG20/#visual-audio-contrast). 177- Except in rare cases, don't remove default `:focus` styles (via e.g. `outline: none;`) without providing alternative styles. See [this A11Y Project post](http://a11yproject.com/posts/never-remove-css-outlines/) for more details. 178 179### JS 180 181- No semicolons (in client-side JS) 182- 2 spaces (no tabs) 183- strict mode 184- "Attractive" 185 186### Checking coding style 187 188Run `grunt test` before committing to ensure your changes follow our coding standards. 189 190 191## License 192 193By contributing your code, you agree to license your contribution under the [MIT license](https://github.com/twbs/bootstrap/blob/master/LICENSE). 194 195Prior to v3.1.0, Bootstrap was released under the Apache License v2.0. 196 197