Pivotal Labs » Doc Ritezel

Using the Style Guide gem

Doc Ritezel — Mon, 21 Jan 2013 13:00:08 +0000

Much like any good Rails engine, using Style Guide is designed to give you as much flexibility as possible. In its default state, Style Guide renders subdirectories full of partials located under app/views/style-guide.

You might be wondering what to do next. Let’s walk through iterating on a partial.

Setting Up the Partial

$ mkdir -p app/views/style-guide/branding
$ mkdir -p app/assets/stylesheets/branding

Now we’ve got a place for our partials and stylesheets to live. Let’s make a partial for the company’s name:

# app/views/style-guide/branding/_headers.html
The Company You Trust

Now we can style them using some SCSS. I heard you like hot pink:

# app/assets/stylesheets/branding/headers.css.scss
.brand-name {
  color: #f0f;
  background-color: black;
  font-weight: 900;
}

Fantastic! It’s like the mid-90s in here.

Iteration in the Style Guide

At this point, Style Guide is ready for iterating until the header is properly-styled. Let’s change the colors around as a stand-in for your actual tweaking process.

# app/assets/stylesheets/branding/headers.css.scss
.brand-name {
  color: #0096D6;
  font-weight: 900;
}

Compared to turning on all the pink pixels in your computer’s screen, that blue is a lot nicer to look at.

Laying Out Partials

A quick note for the sharp-witted: resist the temptation to do full-page layouts inside of Style Guide. Not only does putting layout inside Style Guide pollute the visual elements being styled, it complicates any future refactoring or extraction you might do. Layout nomenclature, an extremely complex issue, is best decided per project.

Let’s say we want to put both headers on the landing page, which will in this case be the “index” action of our “home” controller.

# app/views/home/index.html
Brand Name Company

Let’s say we’re very clever and put the controller and action name onto the body as CSS classes.

# app/views/layouts/application.html.erb
...

...

We’re going to do something very clever with SASS in that will make your head spin:

# app/assets/stylesheets/home.css.scss
.home.index {
  h1 {
    @extend .brand-header;
  }
}


This uses @extend to reduce CSS duplication.  All of a sudden, the rules in .brand-name that we styled are applied to .home.index h1.  Here's what the compiled version of headers.css.scss will look like:
.brand-name,
.home.index h1 {
  color: #0096D6;
  font-weight: 900;
}

Superficially, @extend lets us see all the places where the .brand-name class is applied.  Structurally, and more importantly, @extend separates the implementation of a widget's styling from its layout.
We could have gotten the same structural result with include, but that would have resulted in code duplication.  Likewise, we could have put .brand-name onto the 
, but that would be a stronger coupling.
Multiple States for Partials
Due to an unfortunate Superbowl ad, we need to change the company name's color when the mouse hovers over it.  Due to how browser's work, we can't fake the :hover selector, so we need to make a CSS class to represent the hovered state.  Let's add that to the branding/headers.html partial.
# app/views/style-guide/branding/_headers.html
The Company You Trust
Trust No One

Now we need to style this.
# app/assets/stylesheets/branding/headers.css.scss
.brand-name {
  color: #0096D6;
  font-weight: 900;
}
.brand-name-hover {
  color: #D9541E;
}

Okay, so now both states are styled.  Let's apply the hover style to that 
element to complete the story:
# app/assets/stylesheets/home.css.scss
.home.index {
  h1 {
    @extend .brand-name;
    &:hover {
      @extend .brand-name-hover
    }
  }
}

Wow, now that's some contrast!
Configuring the Style Guide Location
This whole time, we've been putting our files into app/views/style-guide, but this isentirely configurable.  Just pop open your application.rb and change the config.style_guide line.  Let's say you want to put your guide in app/guide instead:
class YourApplication < Rails::Application
  ...
  config.style_guide.paths << Rails.root.join("app", "guide")
  ...
end

Now you're configuring Style Guide like a champ!
The post Using the Style Guide gem appeared first on Pivotal Labs.



Introducing the Style Guide gem
Doc Ritezel — Mon, 14 Jan 2013 13:00:32 +0000
Your Rails application has a unit test suite in RSpec, a set of request specs using Capybara, and a Jasmine suite for your JavaScript. You may even have Cucumber so that your PM can participate in automated testing definition. According to long-standing traditions in Rails testing, your ass is covered.
You have a CSS-shaped hole in your test coverage. You need a style guide. Today, you can quickly set one up on your Rails application with the style-guide gem.


Poor CSS Hygiene is Technical Debt
Here at Pivotal Labs, we’ve run into this conundrum more than once. In the life of a Rails app, more and more pages get added, supported by more and more CSS, and hacks plug more and more holes in the layout. With every commit, even if your Ruby is good looking, you risk adding technical debt.
According to Nicole Sullivan, massively large sites like Facebook and LinkedIn run into the same issues. At one point, Facebook famously defined its blue color an astonishing 260 times more than it should have been. Not only does CSS get larger and more complex as time goes on, the act of paying down that technical debt usually involves acts of heroism.
In short, maintaining CSS on large projects has become a mostly-joyless cross-browser fiasco, desperately in need of tooling.
Testing the Visual Medium
Over the last few years, Pivotal Labs has sometimes extended the test suite metaphor to the visual elements of a Rails application.  In most cases, this is a single page containing the most important visual elements. However, this strategy has existed largely as informal community knowledge.
In unit test suites, the major functions of a block of code are tested against controlled input.  When tests written before implementation, loose coupling and decreased complexity are generally the result. Styling elements in a style guide first can have the same benefits.
As well as being a good system design tool, a unit test suite can also be considered a form of documentation.  Tests describe the behavior of all the code in a system, often exposing the failure cases and exceptions that can happen during execution.  A style guide serves the same purpose for new developers joining a team, efficiently describing all the widgets and states in a site.
As Pivotal Labs grows in size and builds out its design team, the style guide also serves as a communication device between designers and developers. On several projects, the style guide serves as a single point of reference for product owners, developers and designers to talk about their application’s visual elements.
Installing the Style Guide gem
The style-guide Rails engine mounts onto your Rails application at /style-guide by default and renders files out of subdirectories underneath app/views/style-guide.
style-guide also ships with a bunch of Twitter Bootstrap elements by default, which can easily be hidden.
Add the following line to your Gemfile:
gem "style-guide"
Use Bundler to install it:
$ bundle install
Use the Rails generator to set up your project the rest of the way:
$ rails generator style_guide:install
Start Rails and Guard (in their own terminals of course):
$ rails server
$ bundle exec guard
You’re ready to visit Style Guide in its new home, most likely at http://localhost:3000/style-guide.
Stay tuned for part 2: Using Style Guide in your Workflow.
The post Introducing the Style Guide gem appeared first on Pivotal Labs.


The Naked Gemspec
Doc Ritezel — Fri, 14 Dec 2012 19:42:00 +0000
Before we start, the .gemspec itself only appears once.  Here it is, as generated by bundle init and hand-tweaked for relevance:
lib = File.expand_path("../lib", __FILE__)
$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
require "your_gem/version"

Gem::Specification.new do |s|
  s.name        = "your-gem"
  s.version     = YourGem::VERSION
  s.authors     = ["Your Name"]
  s.email       = ["you@example.com"]
  s.homepage    = "https://github.com/you/should-use-github"
  s.summary     = "Describe this gem like you're talking to me."
  s.description = "Describe this gem like you're talking to your mom."

  s.require_paths = ["lib"]
  s.files         = `git ls-files`.split("n")
  s.test_files    = `git ls-files -- spec/*`.split("n")

  s.add_dependency "hashie", "~> 2.0"
  s.add_development_dependency "rspec", "~> 2.12"
end

But what does all this mean?  Moreover, how do all these crazy bits fit together?
Files
The most important component of any gemspec is the list of files that it includes when building the gem.  After all, a .gem file is just a tarball with a metadata header written in Ruby.  Here’s how we make that happen:
s.files         = ['file/one', 'file/two']
s.test_files    = ['spec/one', 'spec/two']

Let’s exploit part of git to give us the list of files.  Don’t use git on your project?  Start using git.  Problem solved!  Here’s what it gives us:
$ git ls-files
.gitignore
.rvmrc
Gemfile
LICENSE
README.md
your-gem.gemspec
lib/your_gem.rb
lib/your_gem/version.rb
spec/lib/your_gem.rb
spec/spec_helper.rb

We can make this output into a Ruby array of strings quite simply:
`git ls-files`.split("n")

Now, gems are laid out in a conventional way.  That means a lib directory, a spec directory and some predictable files.  That means nobody has to guess where your files are, which is fantastic!
Now let’s say you want to exclude your .rvmrc and .gitignore, because those files aren’t really all that important:
`git ls-files`.split("n") - %w(.rvmrc .gitignore)

Note: exclude Gemfile.lock from git, even though it might exist in your directory.  This is conventional.
Naming
Your gem’s classes are called YourGem, while they live in files named your_gem.  As a matter of taste, I believe gems should be named your-gem.  There’s an argument to be made that gem names should match their requires (i.e., the gem should be named your_gem).
Version
The first component here is the version number for your gem.  In this example, the your_gem/version.rb looks like this:
module YourGem
  VERSION = "0.1.0"
end

This is a Semantic Versioning string, and it’s the Simplest Thing that Could Possibly Work for a version.
Dependencies
This is the fun part.  I’m of the opinion that dependencies should be as loose as possible until they’re not, but that throwing them away by doing >= 0 is the wrong approach.
For example, the above file will pull in RSpec as a dependency, but require any version that matches a pattern like 2.y.z, as long as y is above 12.  Note that z is allowed to be anything, which allows patch versions to be included.
Of course, this means that everyone in the community has to play along and not break their gem on a minor version bump.  Also, the community now includes you!
Maintenance
So now you’ve got a conventional gem with loosely-required dependencies.  How do you know if these change?  Well, if you’re on github, you can use Gemnasium to watch for new dependency versions and see if anything’s broken!
Dropping a new version of your gem is as easy as gem release with @svenfuchs‘s gem-release gem.
More Reading

Rubygems Patterns
Semantic Versioning
Clarifying the Roles of the gem spec and Gemfile
The Pessimistic Gem Version Operator

The post The Naked Gemspec appeared first on Pivotal Labs.


Automated Deployment Messages
Doc Ritezel — Fri, 05 Oct 2012 20:15:00 +0000
Make deployment visible with Capistrano, Autotagger, Git and Sendgrid
There comes a time in every project when the deployment process comes of age, and that development arrives with its own set of Capistrano recipes and Rake tasks.  The project I’m on hit that point recently, and one of the neat outcomes of its nascent puberty was a simple Capistrano recipe to send a git changelog to our project mailing list.
Here’s what this looks like:
$ cap staging deploy
... stuff happens here ...
  * executing `sendgrid:notify'
Changelog:
04fc6dd adding capistrano deployment messages

To use this in your Rails project, the first thing you need is a sendgrid account. If you’re budget-minded, you can always use the credentials your Heroku app is using.
$ heroku create
Creating heroku-wackiness-90210... done, stack is cedar
http://heroku-wackiness-90210.herokuapp.com/ | git@heroku.com:heroku-wackiness-90210.git
Git remote heroku added
$ heroku addons:add sendgrid:starter
Adding sendgrid:starter on heroku-wackiness-90210... done, v2 (free)
Use `heroku addons:docs sendgrid:starter` to view documentation.
$ heroku config -s
SENDGRID_PASSWORD=s3kr17
SENDGRID_USERNAME=yodawg@heroku.com

This process uses Capistrano and Autotagger.  For information on setting up Capistrano, their wiki is an excellent starting point.  For Autotagger setup with Capistrano, Jeff Dean’s auto_tagger repository is the canonical source of information.
After you’re up and running with Capistrano and Autotagger, you need to add the following file under lib/recipes/sendgrid_notifier.rb:
require 'mail'

set :sendgrid_user, "whatever"
set :sendgrid_password, "secret"
set :sendgrid_domain, "pivotallabs.com"

set :sender, "Now Hiring "
set :recipient, "Steve Squivot "

namespace :sendgrid do
  task :notify do
    sendgrid = {
      :address   => "smtp.sendgrid.net",
      :port      => 587,
      :domain    => sendgrid_domain,
      :user_name => sendgrid_user,
      :password  => sendgrid_password,
      :authentication => 'plain',
      :enable_starttls_auto => true
    }

    auto_tagger = AutoTagger::CapistranoHelper.new(
      :stage => rails_env,
      :stages => auto_tagger_stages).auto_tagger
    previous_sha = auto_tagger.refs_for_stage(stage).last.sha
    current_sha = auto_tagger.repo.latest_commit_sha

    mail = Mail.new(from: recipient, to: sender)
    mail.delivery_method :smtp, sendgrid
    mail.subject = "[#{stage}] New Deployment!"
    mail.body = `git log --oneline #{previous_sha}..#{current_sha}`
    mail.deliver!
  end
end

Then, let’s add a line to include this recipe in our Capfile:
require File.expand_path("../lib/recipes/sendgrid_notifier.rb", __FILE__)

Finally, let’s try it out:
$ cap ci sendgrid:notify
  * executing `sendgrid:notify'
Changelog:
04fc6dd add a recruiter message to send off to Square

Alright! The email’s on its way. If you need to call this in your custom deployment step, it’s as easy as sticking sendgrid.notify into your Capfile.
Happy deploying!
The post Automated Deployment Messages appeared first on Pivotal Labs.


[Standup][SF] 09/12/12: The Milkshake Fiasco
Doc Ritezel — Wed, 12 Sep 2012 14:51:00 +0000
Events


Chocolate Milkshake Day was announced but not substantiated.

The SF office is now in breathless anticipation of chocolate milkshakes.
 Continue reading →
The post [Standup][SF] 09/12/12: The Milkshake Fiasco appeared first on Pivotal Labs.

Pivotal Labs » Doc Ritezel

Using the Style Guide gem

Setting Up the Partial

The Company You Trust

Iteration in the Style Guide

Laying Out Partials

Brand Name Company

, but that would be a stronger coupling.

Multiple States for Partials

The Company You Trust

Trust No One

element to complete the story: # app/assets/stylesheets/home.css.scss .home.index { h1 { @extend .brand-name; &:hover { @extend .brand-name-hover } } } Wow, now that's some contrast!

Configuring the Style Guide Location

Introducing the Style Guide gem

Poor CSS Hygiene is Technical Debt

Testing the Visual Medium

Installing the Style Guide gem

The Naked Gemspec

Files

Naming

Version

Dependencies

Maintenance

More Reading

Automated Deployment Messages

Make deployment visible with Capistrano, Autotagger, Git and Sendgrid

[Standup][SF] 09/12/12: The Milkshake Fiasco

Events

element to complete the story:

`# app/assets/stylesheets/home.css.scss .home.index { h1 { @extend .brand-name; &:hover { @extend .brand-name-hover } } }`

Wow, now that's some contrast!