diff --git a/docs/migration.md b/docs/migration.md index a03be5dea6..f699cdc3c9 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -3,40 +3,58 @@ layout: page title: Migrating to v4.x.x --- +Bootstrap 4 is a major rewrite of almost the entire project. The most notable changes are summarized immediately below, followed by more specific class and behavioral changes to relevant components. + ## Summary -For a broader overview, see [what's new](http://blog.getbootstrap.com/DEAD-LINK-FIX-ME-PLEASE) in the v4.0.0 release announcement. +Here are the big ticket items you'll want to be aware of when moving from v3 to v4. -- Dropped IE8 support—v4 is now only IE9+. For sites needing IE8, use v3. -- Dropped iOS 6 support. +- Dropped IE8 and iOS 6 support. v4 is now only IE9+ and iOS 7+. For sites needing either of those, use v3. - Added official support for Android v5.0 Lollipop's Browser and WebView. Earlier versions of the Android Browser and WebView remain only unofficially supported. -- Switched from `px` to `rem` as our primary unit in CSS. -- Media queries are now in `em`s. +- Switched from `px` to `rem` as our primary CSS unit. +- Media queries are now in `em`s instead of `px`s. - Global font-size increased from `14px` to `16px`. -- Dropped panels, thumbnails, and wells for a new component, cards. +- Dropped panels, thumbnails, and wells for a new all-encompassing component, cards. - Switched from LESS to SCSS for our source CSS files. - Added a new grid tier for ~`480px` and below. -- Dropped Glyphicons icon font. +- Dropped the Glyphicons icon font. - Dropped the Affix jQuery plugin. We recommend using a `position: sticky` polyfill instead. [See the HTML5 Please entry](http://html5please.com/#sticky) for details and specific polyfill recommendations. - Refactored nearly all components to use more unnested classes instead of children selectors. - Non-responsive usage of Bootstrap is no longer supported. +- Images are now responsive (via `max-width`) by default. - Dropped the online Customizer in favor of more extensive setup documentation. -- Replaced the separate optional theme with... +- Replaced the separate optional theme with configurable options via SCSS variables (e.g., `@enable-gradients: true`). -## Major class changes +## By component This table shows the style changes between v3.x.x and v4.0.0. -| Bootstrap 3.x.x | Bootstrap 4.0.0 | -| --- | --- | -| Pager's `.previous` | `.pager-prev` | -| Pager's `.next` | `.pager-next` | -| Carousel's `.item` | `.carousel-item` | -| Tabs | | -| Pills | | -| Buttons | | +### Tables + +- Nearly all instances of the `>` selector have been removed, meaning nested tables will now automatically inherit styles from their parents. This greatly simplifies our selectors and potential customizations. +- Responsive tables no longer require a wrapping element. Instead, just put the `.table-responsive` right on the ``. +- Changed `.table-condensed` to `.table-sm` for consistency. +- Added a new `.table-inverse` option. + +### Pager + +- Changed `.previous` and `.next` to `.pager-prev` and `.pager-next`. + +### Carousel + +- Changed `.item` to `.carousel-item`. + +## Documentation + +Our documentation has received an upgrade across the board as well. Here's the low down: + +- We're still using Jekyll, but we've got a custom plugin in the mix (`example.rb`) for easier example-code handling. +- All docs content has been rewritten in Markdown (instead of HTML) for easier editing. +- Pages have been reorganized for simpler content and a more approachable hierarchy. +- We moved from regular CSS to SCSS to take full advantage of Bootstrap's variables, mixins, and more. ## What's new + We've added new components and changed some existing ones. Here are the new or updated styles. | Component | Description | @@ -61,7 +79,10 @@ The following components have been removed in v4.0.0. TODO: audit classes in v4 that aren't present in v4 +### Responsive utilities + The following deprecated Less/SCSS variables have been removed in v4.0.0: + * `@screen-phone`, `@screen-tablet`, `@screen-desktop`, `@screen-lg-desktop`. Use the more abstract `$screen-{xs,sm,md,lg,xl}-*` variables instead. * `@screen-sm`, `@screen-md`, `@screen-lg`. Use the more clearly named `$screen-{xs,sm,md,lg,xl}-min` variables instead. * `@screen-xs`, `@screen-xs-min`. The extra small breakpoint has no lower bound, so these variables were logically absurd. Reformulate your expression in terms of `$screen-xs-max` instead.