Permalink
Browse files

Add upgrade guide

  • Loading branch information...
mirisuzanne committed Aug 14, 2012
1 parent fcb8303 commit 6e10da1d85450bf20a940ec5f5a38eb33d67cbdc
Showing with 282 additions and 0 deletions.
  1. +282 −0 docs/source/guides/upgrade-1-0.html.md
@@ -0,0 +1,282 @@
+---
+title: Upgrade to Susy 1.0
+side_content: >
+ <p class="version">Version <span>1.0.rc.4</span></p>
+ <h2>Upgrading from 0.9</h2>
+ <ul>
+ <li><a href="#ref-gem">the gem</a></li>
+ <li><a href="#ref-semantics">semantics</a></li>
+ <li><a href="#ref-upgrade">upgrade</a></li>
+ </ul>
+ <h2>New Features</h2>
+ <ul>
+ <li><a href="#ref-span-columns">span-columns</a></li>
+ <li><a href="#ref-rwd">responsive grids</a></li>
+ <li><a href="#ref-box-sizing">border-box sizing</a></li>
+ <li><a href="#ref-grid">grid shortcuts</a></li>
+ <li><a href="#ref-omega">omega shortcuts</a></li>
+ <li><a href="#ref-container">container settings</a></li>
+ </ul>
+---
+
+## Upgrade to Susy 1.0
+
+This release is loaded with new features,
+but don't let that fool you.
+Susy has become shockingly simple to use.
+
+The interface and syntax have been simplified
+so that the language is consistent and easy to understand.
+We also cleaned-up the output,
+taking into account your Compass browser-support settings,
+and giving you more control over exactly how your grids are built.
+Then we added a load of responsive tools
+and optional new settings
+to make Susy as absolutely flexible as possible.
+
+I'll cover the basics here, but you should
+check out the [reference docs][docs] and [demos][demos]
+for more detail.
+
+[docs]: http://susy.oddbird.net/guides/reference/
+[demos]: http://susy.oddbird.net/demos/
+
+### <a href="#ref-gem" id="ref-gem">The Gem</a>
+
+To start with,
+the gem name has changed from `compass-susy-plugin`
+to simply `susy`.
+
+ :::bash
+
+ # uninstall the old gem !important
+ gem uninstall compass-susy-plugin
+
+ # install the new gem
+ gem install susy
+
+This new gem depends on [Compass 0.12.2][compass]
+(though some features work even better with 0.13.0 alpha)
+and [Sass 3.2.0][sass].
+
+If you don't uninstall the old gem, you will get errors.
+
+[compass]: http://compass-style.org/
+[sass]: http://sass-lang.com/
+
+### <a href="#ref-semantics" id="ref-semantics">Semantic Simplifications</a>
+
+We re-arranged the code
+in order to make the syntax simpler and more consistent:
+
+* `$total-cols` is now `$total-columns`.
+* `$col-width` is now `$column-width`.
+* `$side-gutter-width` is now `$grid-padding`
+ and gets applied directly to the grid container.
+* `un-column` & `reset-column` mixins have merged into `reset-columns`.
+* `columns` has been renamed `span-columns` to resolve the conflict with CSS3 columns.
+ See other improvements to span-columns below.
+
+We also removed several bothersome requirements:
+
+* The `alpha` mixin is no longer needed. Ever.
+* The `omega` no longer takes a `$context` argument.
+* `full` has been removed entirely.
+ Elements will be full-width by default.
+ You can add `clear: both;` back in as needed.
+* `side-gutter()` is no longer needed.
+ You can use the `$grid-padding` setting directly.
+
+### <a href="#ref-upgrade" id="ref-upgrade">Upgrade</a>
+
+That's all you need in order to upgrade from Susy 0.9.
+
+1. Uninstall and re-install the gem.
+2. Find and replace the "semantic simplifications" listed above.
+
+You're done! Stop worrying about all that "nested vs. root" bullshit,
+and start playing with the new toys!
+
+If you use the `$from` directional arguments
+directly in the `span-columns` mixin,
+there may be one more change to make.
+See below:
+
+### <a href="#ref-span-columns" id="ref-span-columns">Span Columns</a>
+
+The `span-columns` mixin now handles many additional use-cases:
+
+ :::scss
+
+ // span-columns(<$columns> [<omega> , <$context>, <$padding>, <$from>])
+ article { @include span-columns(9); }
+
+This means "omega" can be applied directly through the `$columns` argument,
+for much more compact input and output:
+
+ :::scss
+
+ // The OLD way
+ @include columns(4);
+ @include omega;
+
+ // The NEW way
+ @include span-columns(4 omega);
+
+The `omega` mixin still exists as a stand-alone option when needed.
+
+Internal padding can also be added to the element
+through the `$padding` argument,
+without breaking the set column width:
+
+ :::scss
+
+ // The units for $padding must match your grid setup
+ @include span-columns(4, 12, 3em);
+
+ // You can also pass two values for different left and right padding:
+ // The first value will be from-direction, the second is the to-direction.
+ @include span-columns(4, 12, 3em .5em);
+
+This pushes the `$from` argument from third position into fourth.
+If you were using e.g. `span-columns(6,8,right)`,
+you will need to adjust slightly to accompodate the new argument.
+This should not be a common problem.
+
+### <a href="#ref-rwd" id="ref-rwd">Responsive Web Design</a>
+
+Version 1.0 is loaded with responsive tools.
+The main feature is the `at-breakpoint` mixin,
+which can be used to set media-layout combinations:
+For such-and-such media, use such-and-such layout.
+
+ :::scss
+
+ // at-breakpoint(<$media-layout> [, <$font-size>]) { <@content> }
+ // - example: a 12-column grid at the media-query min-width of 30em.
+ @include at-breakpoint(30em 12) {
+ .page { @include container; }
+ }
+
+You can also apply `layout` to use an arbitrary layout,
+or `with-grid-settings` to change any grid settings.
+You can also add breakpoint media-layouts directly to your `container`as a shortcut,
+or use `set-container-width` inside breakpoints
+to adjust the container to it's new context
+without the repetative output from multiple applications of `container`.
+
+Use the global
+`$breakpoint-media-output`, `$breakpoint-ie-output`, and `$breakpoint-raw-output`
+settings
+to turn on and off the different outputs from `at-breakpoint`.
+This is useful when you have IE-overrides living in a file of their own.
+
+[Mason Wendell][Mason Wendell] and [Sam Richard][Sam Richard]
+have created their own [breakpoint][breakpoint] plugin
+based on the same ideas.
+It's the perfect complement,
+for quickly handling your non-grid media-query needs
+without learning a whole new syntax.
+
+[Mason Wendell]: https://twitter.com/codingdesigner/
+[Sam Richard]: http://twitter.com/snugug/
+[breakpoint]: http://github.com/canarymason/breakpoint
+
+### <a href="#ref-box-sizing" id="ref-box-sizing">Border-Box Sizing</a>
+
+Apply the `border-box-sizing` mixin at the root of your document
+(before any other grid mixins)
+to set the border-box model on all elements.
+
+ :::scss
+
+ @include border-box-sizing;
+
+ // other grid code should come after...
+
+This will apply the popular
+`* { box-sizing: border-box }`
+universal box-model fix,
+as well as changing the Susy
+`$border-box-model` setting to `true` for you.
+Susy will make all the necessary grid adjustments from there.
+
+### <a href="#ref-grid" id="ref-grid">Grid Shortcuts</a>
+
+The `space()` function can be used anywhere you need column+gutter math.
+Unlike the `columns()` function,
+this math will include the column-adjacent gutter.
+
+ :::scss
+
+ article {
+ position: absolute;
+ left: space(3);
+ }
+
+In addition to the padding mixins
+(`prefix`, `suffix`, and `pad`),
+you can now manage margins with
+`push`, `pull`, `pre`, `post`, and `squish`.
+
+### <a href="#ref-omega" id="ref-omega">Omega Shortcuts</a>
+
+Omega is often applied to the `nth` element in a set.
+
+ :::scss
+
+ .item {
+ @include span-columns(3,12);
+ &:nth-child(4) {
+ @include omega;
+ }
+ }
+
+Now you can use the `nth-omega` mixin
+to set omega on any
+nth-child, nth-of-type, first, last, or only element.
+
+ :::scss
+
+ // nth-omega([<$n>, <$selector>, <$from>])
+ // $selector options: child (default), last-child, of-type, last-of-type, only.
+ .item {
+ @include span-columns(3,12);
+ @include nth-omega(4);
+ }
+
+You can also remove the omega-specific styles from an element,
+returning it to the regular grid flow,
+with `remove-omega` and `remove-nth-omega`.
+
+### <a href="#ref-container" id="ref-container">Container Settings</a>
+
+* `$container-width` will override the width of your container
+ with any arbitrary length.
+* `$container-style` will override the type of grid container
+ (magic, fluid, fixed, static, etc) to use.
+ All the internals remain fluid,
+ no matter what container style you choose.
+ That's the entire reason Susy exists.
+
+### That's All
+
+We want Susy to be the most flexible,
+semantic, and responsive grid system available.
+While the other systems
+focus on speed by cutting corners
+and making decisions for you,
+our goal is to do the math and get out of your way.
+
+If you see bugs,
+or have ideas for an important new feature,
+or simply have questions,
+come talk to us.
+You can message us on [twitter][twitter],
+or file an issue on [github][github].
+Even better, submit a patch!
+
+Happy coding!
+
+[twitter]: http://twitter.com/CompassSusy/
+[github]: https://github.com/ericam/susy/

0 comments on commit 6e10da1

Please sign in to comment.