Maintaining Open Source Projects: Licenses

- Tute Costa
- May 1, 2015
- Uncategorized

We’re pleased to announce a new chapter on Licenses in our Maintaining Open Source Projects book.

Adding Twitter’s Bootstrap CSS to your Rails app

November 10, 2011

Bootstrap in action, as demoed in Luca Pette's article

Updated Feb 2012 for Bootstrap 2.

Twitter’s new CSS toolkit, Bootstrap, is all the rage these days. I explain how to get the CSS, and optionally the mixins and the JavaScript, into your Rails app.

“How do I serve Bootstrap through Rails 3.1’s asset pipeline?”

Just add Ken Collins’s (@metaskill’s) less-rails-bootstrap gem (announced recently on his blog) to your Gemfile:

1	`gem 'less-rails-bootstrap'`

Require it in your app/assets/stylesheets/application.css:

1	`*= require twitter/bootstrap`

Done. You now have Bootstrap 2 working in your Rails app. :-)

By the way: Did you know that Bootstrap is written in LESS, a stylesheet language like SCSS?

“Ugh, I hate LESS. Can I get Bootstrap as plain CSS please?”

That’s OK, not everybody likes LESS. Behind the scenes, less-rails-bootstrap transparently compiles the Bootstrap LESS files into CSS through Rails’s asset pipeline (using the less-rails gem). This means that there is no scary client-side compilation with less.js (like the LESS website advertises). And on the Rails side, you can just carry on using SCSS. In other words, Bootstrap by default acts like any regular CSS library – all the LESS stuff is hidden from you.

“I love LESS. Can I use the Bootstrap mixins in my LESS code?”

Sure you can. Just import the mixins and variables in any stylesheet file ending in .less (like posts.css.less):

@import "twitter/bootstrap/variables";
@import "twitter/bootstrap/mixins";

div.post {
   color: @yellow;  // <-- using variables
   #gradient.vertical(@black, @blue);  // <-- using mixins
}

Warning: Do not get confused about requiring vs importing:

Use = require twitter/bootstrap at least once (typically in application.css) to get all the CSS rules that come with Bootstrap. The files will be processed through Sprockets (Rails’s asset handler), which guards against duplicate inclusion. If you tried to require the mixins or variables, it would have no effect, since Sprockets compiles them separately from your stylesheets.
Add the two @import lines above to every LESS file in which you want to use Bootstrap mixins or variables. As you can verify by inspecting the CSS output, importing them has no effect (i.e. no CSS rules are generated) until you actually use the mixins and variables in your own CSS rules. If you tried to @import the entire “twitter/bootstrap” library, it would show up multiple times in your compiled CSS assets, because Sprockets can’t guard against duplicate inclusion when you use @import.

To summarize, require the entire toolkit, and @import the mixins and variables.

“Can I use Bootstrap’s JavaScript plugins?”

Easy enough. Add this to your application.js:

1	`//= require twitter/bootstrap`

The plugins load through jQuery’s .ready, so be sure to wrap your own code as well:

1
2
3

$(function() {
  // ...
});

“Now how do I get started using Bootstrap in my layouts and views?”

Try adding a button in any view file – it should be rendered pretty:

1	`<input type="button" value="Click me" class="btn primary">`

Or try adding a black navigation bar to your layout:

<div class="navbar navbar-fixed-top">
  <div class="navbar-inner">
    <div class="container">
      <a class="brand" href="/">Whizboo App</a>
      <ul class="nav">
        <li class="active"><a href="/">Home</a></li>
        <li><a href="/about">About</a></li>
      </ul>
      <ul class="nav pull-right">
        <li><a href="/sign_in">Sign In</a></li>
      </ul>
    </div>
  </div>
</div>

Fore more inspiration, check out Luca’s article about using Bootstrap with Rails.

“I want more explanation. / I heard there is a Sass version of Bootstrap.”

Check out ”Twitter Bootstrap, Less, and Sass: Understanding Your Options for Rails 3.1” on RubySource!

[…]

When Is It Time to Refactor?

January 9, 2014

One struggle for software development teams is determining when it is appropriate to refactor. It is quite a quandary.

Refactor too early and you could over-abstract your design and slow down your team. YAGNI! You’ll also make sub-optimal design decisions because of the limited information you have.

On the other hand, if you wait too long to refactor, you can end up with a big ball of mud. The refactoring may have grown to be a Herculean effort, and all the while your team has been suffering from decreased productivity as they tiptoe around challenging code.

So what’s a pragmatic programmer to do? Let’s take a look at a concrete set of guidelines that can try to answer this question. Generally, take the time to refactor now if any of the following are true:

Refactoring will speed up the task at hand. This is a no brainer, because you’ll get your current work done more quickly, and the refactoring you performed will benefit your team over time. Of course, this is a judgement call, but experienced developers will hone their sense for these cases.
The refactoring is quick and contained. Many refactorings consist of making small changes, generally within a single class. Because you’re altering an encapsulated unit of structure, often these types of changes require no modifications to collaborators or unit tests. The most common example is applying the Extract Method refactoring in order to implement the Composed Method pattern, but other refactorings like Replace Temp with query fall into this category.

Katrina Owen once said:

Small refactorings are like making a low cost investment that always pays dividends. Take advantage of that every time.

Remember, source code is generally “Write once, read hundreds (or thousands) of times”. Spending a little extra time now cleaning up the internal structure of your classes makes them more approachable to every developer who opens that source code file in the future.
The un-factored code has three strikes. Keep track (either in the back of your head or documented somewhere) of each time you run into a problem or friction that would have been avoided if your code had been better factored. When a given problem spot causes your team trouble three times, it’s time to clean it up. This allows you to focus on the issues that are actually slowing your team down, not just the areas that seem messy.
You’re at risk of digging a hole that will take more than a day to fix. The worst code in every app is usually stuck in god objects that feel almost impossible to refactor, but it wasn’t always this way.

A key practice to employ when considering a larger refactoring is asking yourself this question:

“If I pass on doing the refactoring now, how long would it take to do later?”

If it would take less than a day to perform later, there is less urgency to do it now. It means that if a change needs to be made later, you can be confident you won’t be stuck in the weeds for days on end to whip the code into a workable state in order to implement the feature or bug fix.

Conversely, if passing on the refactoring creates a risk of digging technical debt that would take more than a day to resolve, it should probably be dealt with immediately. If you wait, that day could become two, or three or four days. The longer the time a refactoring takes, the less likely it is to ever be performed.

So it’s important to limit the technical debt you carry to issues that can be resolved in short order if they need to be. Violate this guideline, and you increase the risk of having developers feel the need to spend days cleaning things up, a practice that is sure to (rightly) make your whole organization uneasy.

[…]

The Ruby Rails Aggregator