You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: CONTRIBUTING.md
+64-15
Original file line number
Diff line number
Diff line change
@@ -29,13 +29,36 @@ restrictions:
29
29
their respective repositories).
30
30
31
31
32
+
## Issues and labels
33
+
34
+
Our bug tracker utilizes several labels to help organize and identify issues. Here's what they represent and how we use them:
35
+
36
+
-`browser bug` - Issues that are reported to us, but actually are the result of a browser-specific bug. These are diagnosed with reduced test cases and result in a issue opened on that browser's own bug tracker.
37
+
-`confirmed` - Issues that have been confirmed with a reduced test case and identify a bug in Bootstrap.
38
+
-`css` - Issues stemming from our compiled CSS or source Less files.
39
+
-`customizer` - Issues with our web-based Customizer.
40
+
-`docs` - Issues for improving or updating our documentation.
41
+
-`examples` - Issues involving the example templates included in our docs.
42
+
-`feature` - Issues asking for a new feature to be added, or an existing one to be extended or modified. New features require a minor version bump (e.g., `v3.0.0` to `v3.1.0`).
43
+
-`grunt` - Issues with our included JavaScript-based Gruntfile, which is used to run all our tests, concatenate and compile source files, and more.
44
+
-`help wanted` - Issues we need or would love help from the community to resolve.
45
+
-`js` - Issues stemming from our compiled or source JavaScript files.
46
+
-`meta` - Issues with the project itself or our GitHub repository.
47
+
48
+
For a complete look at our labels, see the [project labels page](/twbs/bootstrap/labels).
49
+
50
+
32
51
## Bug reports
33
52
34
53
A bug is a _demonstrable problem_ that is caused by the code in the repository.
35
54
Good bug reports are extremely helpful, so thanks!
36
55
37
56
Guidelines for bug reports:
38
57
58
+
0.**Validate and lint your code**—[validate your HTML](http://html5.validator.nu)
59
+
and [lint your HTML](https://github.com/twbs/bootlint) to ensure your
60
+
problem isn't caused by a simple error in your own code.
61
+
39
62
1.**Use the GitHub issue search**— check if the issue has already been
40
63
reported.
41
64
@@ -44,7 +67,7 @@ Guidelines for bug reports:
44
67
45
68
3.**Isolate the problem**— ideally create a [reduced test
46
69
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.
70
+
[This JS Bin](http://jsbin.com/lefey/1/edit?html,output) is a helpful template.
48
71
49
72
50
73
A good bug report shouldn't leave others needing to chase you up for more
@@ -72,6 +95,22 @@ Example:
72
95
> causing the bug, and potential solutions (and your opinions on their
73
96
> merits).
74
97
98
+
### Reporting upstream browser bugs
99
+
100
+
Sometimes bugs reported to us are actually caused by bugs in the browser(s) themselves, not bugs in Bootstrap per se.
101
+
When feasible, we aim to report such upstream bugs to the relevant browser vendor(s), and then list them on our [Wall of Browser Bugs](http://getbootstrap.com/browser-bugs/).
| Mozilla | Firefox | Gecko |https://bugzilla.mozilla.org/enter_bug.cgi| "Core" is normally the right product option to choose. |
106
+
| Apple | Safari | WebKit |https://bugs.webkit.org/enter_bug.cgi?product=WebKit <br> https://bugreport.apple.com| In Apple's bug reporter, choose "Safari" as the product. |
107
+
| Google, Opera | Chrome, Chromium, Opera v15+ | Blink |https://code.google.com/p/chromium/issues/list| Click the "New issue" button. |
108
+
| Microsoft | Internet Explorer | Trident |https://connect.microsoft.com/IE/feedback/LoadSubmitFeedbackForm||
109
+
110
+
### Issues bots
111
+
112
+
[@twbs-lmvtfy](https://github.com/twbs-lmvtfy) is a Bootstrap bot that hangs out in our GitHub issue tracker and automatically checks for HTML validation errors in live examples (e.g. jsFiddles, JS Bins, Bootplys, Plunks, CodePens, etc.) posted in issue comments. If it finds any errors, it will post a follow-up comment on the issue and point out the errors. If this happens with an example you've posted, please fix the errors and post an updated live example. If you opened a bug report, please check whether the bug still occurs with your revised, valid live example. If the bug no longer occurs, it was probably due to your invalid HTML rather than something in Bootstrap and we'd appreciate it if you could close out the GitHub issue.
113
+
75
114
76
115
## Feature requests
77
116
@@ -96,6 +135,17 @@ Please adhere to the [coding guidelines](#code-guidelines) used throughout the
96
135
project (indentation, accurate comments, etc.) and any other requirements
97
136
(such as test coverage).
98
137
138
+
**Do not edit `bootstrap.css`, `bootstrap-theme.css`, or `bootstrap.js`
139
+
directly!** Those files are automatically generated. You should edit the
140
+
source files in [`/bootstrap/less/`](https://github.com/twbs/bootstrap/tree/master/less)
Similarly, when contributing to Bootstrap's documentation, you should edit the
144
+
documentation source files in
145
+
[the `/bootstrap/docs/` directory of the `master` branch](https://github.com/twbs/bootstrap/tree/master/docs).
146
+
**Do not edit the `gh-pages` branch.** That branch is generated from the
147
+
documentation source files and is managed separately by the Bootstrap Core Team.
148
+
99
149
Adhering to the following process is the best way to get your work
100
150
included in the project:
101
151
@@ -149,30 +199,30 @@ included in the project:
149
199
**IMPORTANT**: By submitting a patch, you agree to allow the project owners to
150
200
license your work under the terms of the [MIT License](LICENSE.md).
151
201
202
+
### Pull request bots
203
+
204
+
[@twbs-rorschach](https://github.com/twbs-rorschach) is a Bootstrap bot that hangs out in our GitHub issue tracker and automatically checks all pull requests for a few simple common mistakes. It's possible that Rorschach might leave a comment on your pull request and then close it. If that happens, simply fix the problem(s) mentioned in the comment (there should be link(s) in the comment explaining the problem(s) in detail) and then either:
205
+
206
+
* Push the revised version to your pull request's branch and post a comment on the pull request saying that you've fixed the problem(s). One of the Bootstrap Core Team members will then come along and reopen your pull request.
207
+
* Or you can just open a new pull request for your revised version.
208
+
209
+
[@twbs-savage](https://github.com/twbs-savage) is a Bootstrap bot that automatically runs cross-browser tests (via [Sauce](https://saucelabs.com) and Travis CI) on JavaScript pull requests. Savage will leave a comment on pull requests stating whether cross-browser JS tests passed or failed, with a link to the full Travis build details. If your pull request fails, check the Travis log to see which browser + OS combinations failed. Each browser test in the Travis log includes a link to a Sauce page with details about the test. On those details pages, you can watch a screencast of the test run to see exactly which unit tests failed.
210
+
152
211
153
212
## Code guidelines
154
213
155
214
### HTML
156
215
157
-
- Two spaces for indentation, never tabs.
158
-
- Double quotes only, never single quotes.
159
-
- Always use proper indentation.
216
+
[Adhere to the Code Guide.](http://codeguide.co/#html)
217
+
160
218
- Use tags and elements appropriate for an HTML5 doctype (e.g., self-closing tags).
161
219
- 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
220
- Use [WAI-ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) attributes in documentation examples to promote accessibility.
163
221
164
222
### CSS
165
223
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.
224
+
[Adhere to the Code Guide.](http://codeguide.co/#css)
225
+
176
226
- When feasible, default color palettes should comply with [WCAG color contrast guidelines](http://www.w3.org/TR/WCAG20/#visual-audio-contrast).
177
227
- 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
228
@@ -193,4 +243,3 @@ Run `grunt test` before committing to ensure your changes follow our coding stan
193
243
By contributing your code, you agree to license your contribution under the [MIT license](https://github.com/twbs/bootstrap/blob/master/LICENSE).
194
244
195
245
Prior to v3.1.0, Bootstrap was released under the Apache License v2.0.
0 commit comments