Document This

Reasons to use a light on dark color scheme

2013-06-23T00:00:00-07:00

It’s not just to be cool.

You’ll often see developers working with a light-on dark color scheme for their web sites, editors, and other applications. I obviously have a dark scheme on this site, and all my primary desktop editors use a dark color scheme. I use a dark terminal, a dark desktop background, and dark themes on every application that supports theming. You might think this is only due to contemporary media branding dark themes “cool” or “retro,” but there’s actually some marginally good reasons for it.

You might save power.

It might seem silly, but having a darker theme can actually save you a small but measurable amount of power. Blackle claims to save watts by rebranding the Google search homepage with a dark scheme. Google refuted this in 2007, claiming that black schemes might actually increase power usage because in many monitors, the white is always on and the black requires energy to block the light. PCStats set out to test the claims in 2012. In their testing, a dark color scheme saved 4 watts on their reference LCD monitor. CRT monitors had an even more drastic difference, though at this point they are all but completely obsolete. As of this writing, Blackle claims to have saved over 3.5 million watt-hours of energy by users visiting their site instead of Google’s home page; though exactly how they measure this, I’m unsure.

However, not all monitors are LCD, so I’m sure this is up for a lot of debate. In an LED monitor (or, more drastically, something like a Jumbotron), where the light actually turns off in black pixels, the power difference between a full black and white screen is probably even more prominent.

You might sleep better.

Our sleep is affected in part by a hormone called melatonin. Melatonin promotes sleep and, in effect, tells the body “It’s night now, do night things.” Light hitting the retina surpresses the production of melatonin, and can affect your sleep schedule. According to one study, blue light especially kept subjects awake and alert for up to an hour after exposure. By having a darker scheme, you get less blue light and can get to sleep more normally. There are of course other ways to achieve this - for example, a light red background - but in the abscence of other choices, a black or grey background will affect your sleep far less than a bright white one.

It is easier to scan.

This part mostly applies to code or terminal windows, but according to some, light text on a darker background is easier to quickly read in short scans. This is because white light, being made of every color combined, stimulates every color receptor in the eye. The extra light stands out in contrast to the background and is easy to scan across. The lighter the text, the more pronounced the effect - notice how easy it is to quickly scan the title of this post. However, brighter text also tends to become blurred and strain the eyes due to scattering, which makes reading a full paragraph of bright white text on a full black background very stressful on the eyes. To mitigate this, light grey/dark grey schemes like this one are generally used for longer text such as this paragraph.

Older readers may have an easier time with it

According to the American Federation for the Blind, “Contrast is one of the most critical factors in enhancing visual functioning.” They suggest that text always be printed with the best possible contrast to allow sight impaired users to consume it more easily. They mention that for many older people a light-on-dark scheme is easier to read than black on white. This is the origin of both the “high contrast” and “inverted colors” schemes available in many operating systems. This generally isn’t a concern for most code editors or tech sites, but if you’re aiming for an older audience, you may want to consider adding these options.

Of course, there’s data that goes the other way on this, as well. People with astigmatism may have a harder time reading light on dark text. Because the iris must open wider to take in the decreased light, their lens deformation is exaggerated and contributes to fuzzy looking text.

I’m not suggesting every web site run out and switch to a light on dark theme, obviously. But next time you see someone with a dark color scheme, it might not just be because it’s freaking cool.

Ways to version your API, Part 2

2013-05-16T00:00:00-07:00

Part two: How to architect a version-less API

This is part two of a series on API versioning. Part One covered the prevailing methods for versioning your API and allowing clients to code against one version specificically. I suggest you read that post (at least skim the intro!) before this one as it provides some neccesary context. In it, I hinted to another method utilizing some little-known concepts of the Accepts header spec might allow you to make a version-less API. I’ll admit right up front, however, it’s a bit of a misnomer, but I think it’s still important. You can still version things in the API, but you aren’t versioning the interface itself. You’re merely versioning the resource representations.

The most common change in any REST architected API is adding, changing, or removing fields from the resources. New information is added or may be in a different format. Information may become unavailable. You may also add, move, or remove resources themselves. Depending on your API architecture, the HTTP verbs may mean slightly different things. All of these typically would require an API version increment if they would cause existing applications to break. With a little forethought, however, your API can change without requiring a whole API versioning strategy.

Architect a versionless interface:

Use sane URI schemes: /api/collection_name/resource_id
Follow definitions of HTTP methods
Adding resources should always be backwards compatible
Removing resources would have to be done across versions anyway
Moving resources can be handled by redirect HTTP codes

Version resource representations:

Use the Accepts header
Adding information should always be backwards compatible
Removing information would have to be done across versions anyway
Moving information can be done with Accepts versioning

Architecting a version-less API

Let me begin by saying that I acknowledge that a version-less API is a bit of an ideal state, and an API with a well-thought versioning strategy is far preferable to an API with a poorly thought out attempt to not version. There’s no shame in saying that you think you need versioning, nor can every possible API fit into this versionless strategy. It really only works for REST-architected, resource manipulation based APIs that follow prevailing standards. That said, a great deal of APIs can be reworked to fit into this style. Additionally, this is intended for backend APIs, not APIs interfacing with your web front-end. In my opinion, these should almost always be separate APIs so that you can update the web front end functionality at your own pace without worrying about any users of the API. I know I personally am a lot more lax in my following of standards for front-end APIs.

The first step of understanding how to create a versionless API is knowing that you don’t want to version the interface itself. That means, you don’t want to change how and where information is stored and accessed. In practical terms, this is the URI structure. Even this rule can be bent, of course - built right into the HTTP spec are redirects! If you’ve moved information, simply provide a permanent redirect to the new URI. Now, what happens if you remove a resource?

There’s two reasons a particular URI might be removed from a typical API: Either the resource type itself has been removed, or more commonly, that particular representation of the resource is no longer supported. In the latter case, you’re not really adhering to REST architecture: The resource representation should be decoupled from the URI. In the former case, if the entire resource type no longer is accessible, it’s probably for a business reason, in which case you’d want to remove it from all previous versions of the API as well. In that case, versioning didn’t really get you anything, did it?

Adding resources, or information to resources, should always be a backwards-compatible change. If you’re using JSON, adding elements to existing resources should be a breeze. Even if you have an XML schema, you can simply add them to the defined schema and alert clients who may have downloaded their own copy of the schema to update it. If you’d like to add an entirely new resource, simply add it! Nobody should be affected.

Probably the most difficult thing to make versionless is any changes to what happens when you perform a particular method on a particular API. For example, if you used to be able to POST to /api/foo/ and have it create a new foo resource for you, but now you want it to edit an existing foo resource. The best I can tell you is dont, instead follow the recommended HTTP spec method definitions explicitly:

GET /api/foo/ or GET /api/foo/1 retrieves resources or resource collections and is idempotent (repeatable with the same results)
POST /api/foo/ creates new resources and is NOT idempotent (repeating creates more resources)
PUT /api/foo/1 updates or creates an entire specific resource and is idempotent
PATCH /api/foo/1 (proposed standard) updates fields of a specific resource and is idempotent
DELETE /api/foo/1 deletes a resource (sometimes resource collections) and is idempotent

Technically, I think DELETE should notify somehow if the resource didn’t exist in the first place and a proper way to do that would be an error, but I’ll defer on that one. OPTIONS and HEAD are used less and if you’re using them, you probably know what you’re doing anyway. If you’re using PATCH, be aware it isn’t a well supported standard, and many APIs will accept incomplete PUT requests and only update changed fields. I think this is fine so long as it’s a well understdood and documented behavior given spotty PATCH support, at least until it’s more widely acceptable.

A lot of times, resources are modified by POST requests. A form submits, you interpret the data and change a resource. This is a common pattern in front-end APIs, and as I mentioned above, that’s fine. Not perfect, but fine. In a back-end API, this shouldn’t happen! Use a PUT or PATCH request and explicitly define what you want the new resource to be. A common excuse is old versions of IE don’t support PUT or PATCH, but this is a back-end API, it’s fine! Every major library I know of at least supports PUT - if you’re using one that doesn’t, you should probably look elsewhere.

In short, a prerequisite to versionlessness is that every resource you have should be able to be accessed and manipulated in a consistent fasion, with the only directives being the URI to the resource, HTTP method, and the data representing the resource itself. If you’re manipulating a single logical resource - say, a user profile - from multiple URIs, you’re likely going to encounter situations where you need to version.

Versioning resource representations

As I mentioned in the intro, the resource representations themselves transferred to the client can and probably should be versioned. The beauty of this approach is that each resource can be versioned independently. If you change one resource, then a month later decide to change a different resource, you don’t have to increment an API version counter twice. Each resource version is incremented individually. Note that I’m not talking about versioning the resources themselves, just the representation of the resource. If you have a versioned resource, for example a document that has previous revisions available, these should be accessed separately than the method I’m describing here.

Familiarizing yourself with the Accept header spec will probably help you understand the true depth of how far specs can go towards future-proofing themselves. Almost everyone knows the Accepts header specifies what kind of MIME-Type the requestor expects, like application/json. Fewer know that it can not only specify one type, but it can specify multiple acceptable types as well as parameters on each type. In order to version resource representations, we’re going to take advantage of the type parameters.

I’ll jump in and have you consider the following:

application/vnd.example.foo+json;version=2,application/vnd.example.foo+json

Even without fully understanding the Accepts header, you can probably guess this string implies that it expects the application/vnd.example.foo type in json format, version 2 if available, and any version otherwise. Parsing the Accepts header in a manner consistent with the spec can be difficult only because many libraries do not parse it out of the box.

So, when should you version resource representations? As I mentioned above, if you’re removing information about a resource, it’s probably for a business reason that you don’t want it exposed anymore. In today’s age of compressed transmission, there’s little gain to be had from removing information simply because you don’t feel it is useful anymore. Adding information should always be possible to be done in a backwards-compatible manner. You might want to version in cases of changing the name and/or type of a field, for example if you want to (real world example time!) repurpose a boolean field labeled “enabled” to a more generic “status” enum type.

Now, how do I do this?

Unfortunately, much of what I’ve discussed here has little to no broad support in the community of people actually building widely used APIs. I suspect no small part of this is due to the difficulty implementing these in a real world application. Depending on your platform it may be easy or difficult, and few libraries will support a versioning strategy like this out of the box. The closest I know if is node-restify which supports versioned routing based on an Accepts-version header.

I’m going to be going through some libraries and attempting to extend them to support versioning in the future. Possibly attempting my own library that bakes a lot of this in for free. The easier it is for a developer to write standards-compliant code, the more likely they will adopt it, because in the end if it comes down to ease of development vs adherence to standards, I think we all know ease will win out every time.

Ways to version your API

2013-05-09T00:00:00-07:00

Part one: Pros and cons of various methods to version your API

Anyone designing an HTTP API with versioning in mind for the first time might be surprised to learn there is no universally accepted method, nor any standard explaining how. This post will be part one of a two part series on API versioning. In this post, I’ll cover some API versioning methods used today and the pros and cons of each. In part two, I’ll be describing some strategies you can keep in mind when designing your API to obviate the need to version at all.

There’s a lot of ways to version your API, and if you’ve ever had to change your API drastically, you’ve probably been glad you had a versioning methodology in place. If you didn’t, you probably WISH you did. However, anyone designing such a methodology for the first time might be surprised to know there is no universally accepted method for versioning your API, nor does any standard specify one.

Here’s what I have found to be the most common methods of API versioning, in order of least to most desirable in my opinion:

Changing hostnames
Adding /v1/ to the URI
Adding ?version=1 to the query parameters
Passing a custom header
Specifying a parameter in the accepts header

Before I can do that, I must explain what the standards say and explain my interpretation of what the web was envisioned to be.

A URI - Uniform Resource Identifier - is defined in RFC 3986 as a compact sequence of characters that identifies an abstract or physical resource. URIs are, for practical purposes, a superset of URLs (Uniform Resource Locators) and the terms are often used interchangably, if incorrectly. Any API which operates over HTTP at one point has to deal with what URIs point to what resource; whether that is one global resource which all operations flow through or a subnet of resources in a logical arrangement. However, it is important to note that the URI does not specify whatsoever the representation of the resource. This will be important later.

The specification itself does not indicate a URI always has to point to the same resource, though you tend to break client applications if you move resources without warning. As such, if you change your URI scheme, you should either leave the existing URI scheme in place, or leave breadcrumbs to find the new resources. Leaving breadcrumbs will be covered in the next post, so let’s talk about how to change your API while letting people still use it the old way. Keep in mind that these are all general opinions: Sometimes your specific API needs will make one choice drastically better than another that I said was better, so always use your own judgement!

Changing Hostnames

I’m going to barely touch upon this method, since it’s barely used, and even then only in the most extensive of API revamps. Essentially, you’re moving the API from one hostname to another. You might even just call this building a new API to the same resources. Downsides of this method are above and beyond all others - in addition to changing what URIs are being used, clients may have to change their security settings to access the new hostname. The only upside is that you can completely revamp the enture URI structure - including adding a version parameter if you didn’t have one before. You can also easily route it to a completely different server, so the old one can continue serving just the old API. But then you’ve got two servers - Expensive!

Short story: Don’t consider this unless you really messed up the first time and want to completely start over.

Adding version to the URI path

This is by far the most common method currently in use by APIs today. It’s fairly straightforward from an initial implementation standpoint. Simply add a /v1/ or similar to the URI, like this: http://example.com/api/v1/foo/bar. Alternately, you can avoid putting v1 in the URI initially, and if you have to version, change the URI to http://example.com/api_v2/foo/bar.

It’s very easy to code into the first API, and it’s very easy for users to understand what that number means. You can change the entire path after the version number between revisions and not break existing clients. Depending on what server technology you are using, it may be easy or hard to increment the version. If you need to copy and paste code to make this method work, you might want to stay away - it makes the separation very easy, but maintenance can be difficult. Imagine if you had to fix a bug for all versions of the API, and you’re already on version ten! Find-and-replace nightmare.

Deprecating a version - if you do it nicely - can be straightforward, and even easy in some technologies. Redirect all requests to the old, deprecated version resources to a newer version. You’ll still want to notify users ahead of time, but this way their clients might not break when you deprecate a version. Since nobody can not use a version, you’ll potentially break everyone if you don’t give them enough time.

Short story: If you read this entire article (and the followup) and still have no idea what you’re doing, just stick /v1/ in the URI somewhere and figure it out later. This method works for everyone else in the end, you can probably get it to work too - even if you may regret it later.

Version in the query parameters

This one is, in my experience, the second most common versioning method. Again, it is straightforward from an initial implementation standpoint: Add version query parameter, even if it is completely ignored. URIs might look like this: http://example.com/api/foo/bar/?version=1

One advantage of this option is it can be optional or required depending on how you want the API to be used. Some APIs require every request to include the version, others assume the latest version if the request left it off. Like adding it to the URI path, this is very easy to see, understand, and initial code implementation is trivial. In fact, you can probably just ignore it until you actually have a v2!

However, you can’t as easily change the path, so moving resources can be painful. Additionally, you’re often forced to put in place transform layers to change the data representation between versions if the representation has changed. You generally don’t redirect solely on a query parameter being wrong, so redirecting existing users on a deprecated version to a supported version generally can’t be done. However, you can do this transparently by silently serving up the newer version if you think that’s more appropriate than simply breaking.

If you have an API that actually versions resources themselves through query parameters, you’ll probably want to stay away from specifying API version in the query parameters as well. That could get confusing! Use either of the methods below instead.

Short story: An acceptable method when you only want to version the resource representations. Versioning paths will be harder, so keep that in mind. Few benefits over adding it to the URI path.

Passing a custom header

This method is similar to the previous; instead of specifying it in the query parameters you specify it in the headers. For example, to use cURL to get from an API like this, you would specify curl -H "Accepts-version: 1.0" http://www.example.com/api/foo/bar

Largest advantage of this scheme is mostly semantics: You aren’t cluttering the URI with anything to do with the versioning. The URI should be specifying what the resource is, not how you want it represented. However, you also are making up headers. While from a technology standpoint it will work, it loses some purism points.

Other benefits include easily being able to ignore it or silently upgrade if the user does not specify, or specifies a deprecated version. Downsides are similar to version in the query parameters. Additionally, depending on what tools you have it can be difficult to specify. Hint: Get Postman for Chrome, it makes specifying headers easy!

Short story: A neater way to version than with query parameters, and avoids some complications. However, it can be difficult from a usability standpoint.

Specifying a parameter in the Accept header

For now, I’ll simply mention that the Accept header spec allows for custom vendor media types, and for parameters to be passed as part of the content negotiation. This is a perfectly valid Accepts header: “application/vnd.urthen.example?version=1.0”

I’ll be going over this method in much more detail in part two of API Versioning. To understand why this method is ideal in my opinion, you’ll also need to understand my thoughts on how to create an unversioned API. Make sure to follow me on twitter to know when it is posted.

Pros and cons of Amazon SimpleDB

2013-04-29T00:00:00-07:00

Or, why the easiest solution isn’t always the best

Amazon’s SimpleDB service is a very easy to set up and maintain non-relational data store, hosted in their cloud infrastructure. I used it during the creation of a new project as I wanted something simple and easy to implement. SimpleDB was just that. However, it has quite a few limitations. Without getting into too much detail, make sure you take the following into account before you start coding:

The Good

Easy to set up - No special configuration required, just one command to initialize the store.
No Maintenance - Assuming Amazon doesn’t go under, your data is relatively safe
Low cost - Nearly free for small data sets and throughput
Query syntax based on SQL
Exposed in the Python Boto package for Amazon services

The Bad

Slow to write - Can only write a maximum of 25 entries at a time
Slow to read - Can only read ~1kb of data per request
Flat structure - If you input nested JSON objects, you need to parse the deep objects out of packed strings

Conclusions?

In short, it’s a fine service - if you use it correctly. I was trying to use it as a caching service, however. At only 5000 entries, it takes several seconds to read the entire data set, even with no further calculations, just retrieving the data. This was after minimizing the data returned so that I could read the maximum amount before reaching the 1kb limit. I think I’ll soon be switching to something more appropriate. I know Redis will be up to the task, I just need to figure out how to host it properly.

If you’re writing data fairly slowly, and don’t need to read the entire data set rapidly either, it might suit your purposes. This isn’t a condemnation of SimpleDB by any means, just don’t try and make it do things it wasn’t meant to!

Explorations in Python and TeamCity

2013-04-24T00:00:00-07:00

Experiments performing continuous integration testing in Python with TeamCity

At Bazaarvoice, we use TeamCity for continuous integration testing. This has proved immensely useful for most of our Java projects, however as I am developing a Python application, I wanted to see if I could get TeamCity to run testing on my program. I already had a set of unit tests with pretty good code coverage, running fairly fast on my dev machine, so this was mainly an exercise to keep myself honest and track mistakes. No longer could I conveniently “forget” to run the tests before deploying, I want publicly fail within moments of pushing buggy code to master!

While proper unit testing is a topic covered elsewhere in far more detail and with far more expertise than I can provide, I want to share one tidbit that I have found to be the most important moment of “oh, now I get it…” as I’ve been learning how to properly design unit testing. Anytime something breaks, whether it’s in production, QA, or on your dev machine, immediately make sure there’s a corresponding unit test that breaks as well. If there isn’t, write one before fixing the bug. That way you’re sure it won’t happen again. I won’t overly evangelize unit testing, as I’ve been on teams who use it as a crutch, but with this one rule you can save yourself hours fixing bugs you’ve already fixed.

Anyway, as it turns out, JetBrains has already released a module called teamcity-messages, available via easy_install or pip. This module provides hooks for the unittest, nose, and py.test unit testing frameworks in Python. I’m simply using unittest, though I imagine working with the other two is similarly easy. The module is designed to be able to detect whether or not the test is being run from TeamCity, and if so, format the output in a way that TeamCity can immediately report and track tests as they run. When I started my project and unit tests took five seconds to run, there wasn’t much point, but now that unit testing takes a minute or so it can be helpful. For some of our larger projects which take an hour or more to run the full test suite, it’s critical to see failures immediately.

Adding teamcity-messages to your tests

Using unittest with tests split into multiple modules can be fairly boilerplate - have one testing script that uses unittest.defaultTestLoader, then use unittest.TextTestRunner to run the loaded suite of tests. teamcity-messages plays perfectly into that, as all you need to adjust is what runner you use. Here’s my current code:

from teamcity import is_running_under_teamcity
from teamcity.unittestpy import TeamcityTestRunner
import unittest
from tests import testApp, testService, (etc...)

if __name__ == '__main__':
    if is_running_under_teamcity():
        runner = TeamcityTestRunner()
    else:
        runner = unittest.TextTestRunner()

    suite = unittest.defaultTestLoader.loadTestsFromModule(testApp)
    suite.addTests(unittest.defaultTestLoader.loadTestsFromModule(testService))
    (etc...)
    runner.run(suite)

The only change from when I originally wrote the test file was checking to see if we were running under TeamCity, and loading the appropriate test runner. Now, the testing script will run all my tests on both my development machine and TeamCity. No adjustments were needed to any of the tests themselves.

Getting your agents running

Now that we’ve got our tests reporting to TeamCity when they are actually run there, lets get them running there. Turns out, this was actually the harder part of the operation. The first step was setting up the VCS root to read from the project on GitHub. This was simple to do from the build configuration settings, and we were able to leave most options at default. Then, in the ‘Build Triggering’ section, set up a trigger to build after every VCS change. That is, anytime a change to the branch TeamCity is listening to (default is master, but can be changed), it’ll perform the build steps. This means you should probably have developers pushing code directly to their own branches, and only push to master when it’s ready for public consumption - even if that doesn’t mean a release.

The build steps, too, were fairly simple. In addition to my Python unittest script, I also use Grunt to lint my code. Adding these was as simple as adding two Command Line build runners: python26 testing.py for the Python tests, and node_modules/grunt/bin/grunt to run Grunt. Python26 was selected due to version conflicts on the build agents. I ran Grunt that way so it didn’t have to actually be installed, it could be in the source code.

However, this was pretty much the end of the simple tasks. Turns out, it isn’t perfectly straightforward to install python requirements onto a build agent. For our purposes we ended up installing the requirements on all the agents manually, however to keep this working in the future we’d have to add this step to the build agent deployment script. Additionally, once I added some dependencies to AWS services, transferring the IAM credentials to the testing boxes proved to be a challenge we never ended up surmounting before my DevOps engineer working on the project shifted off, and I needed to continue myself.

In Conclusion

Unfortunately, I’m somewhat sad to say (given how much work went into it) that my TeamCity build configuration is paused with the solemn message “Discontinued until I figure out how to make it run without errors.” I still run the same exact tests locally, and as I am the only engineer on the project I have no pressing need to ensure all code is tested as it is checked in. In the future, there’s a couple things I’d like to do to fix things, however.

I believe I can install the Python modules to the agents as local modules, rather than global installations. I always use virtualenv, so my requirements.txt stays up to date. Since the build runners don’t have root permissions, I can’t install packages globally. Neither can I easily set up virtual environments on the build agents. I believe I can install them to the source directory with some variation of pip install --install-option="--prefix=$PREFIX_PATH" package_name but I haven’t gotten into testing this.

As for the AWS credentials, I’m not sure how I’ll get them into the build agents. I’m sure other teams have done something so once I get the packages installing correctly, I will ask around. Another alternate is simply mock out all AWS services. For some functions like sending email this makes the most sense anyway.

Hopefully soon, I’ll be back up and running with TeamCity and will make a new post about the changes. Until then, I’ll dutifully maintain my unit testing locally in the hopes it may become automated again in the future.

Deploying a blog to Github in 30 minutes or less

2013-04-20T00:00:00-07:00

An introduction to installing and setting up Jekyll

There’s a whole lot of ways out there to start a blog. From WordPress to Blogger to Tumblr, you can set up your own soapbox in a matter of moments. Some of us, however, desire a more hands-on approach. Fortunately there’s a way to have a completely self-managed blog without having to spend a dime on hosting costs.

Enter Github Pages. GitHub will let you create and host static HTML pages, or pages written with Markdown. Additionally, it’ll let you deploy with a templating language called Jekyll, allowing you to quickly and easily deploy blog-like pages. A final piece of the puzzle: Jekyll Bootstrap, a fully-featured themable blog framework that takes most of the work out of setting up a simple blog. There’s excellent documentation on the Jekyll Bootstrap site detailing the very few steps neccesary to get yourself up and running. I’ll be going over everything from “Hm, I should start a blog…” to “Hey, that was easy!”

Installation

First, you’ll want to make sure you’ve got Ruby installed. If you’re running a Mac, it probably already is. Once you’ve got that, install Jekyll with gem install jekyll. Now create the your-username.github.com repository in GitHub… replace your-username with your actual GitHub username, of course. That’s it for prerequisites, and if you’re on schedule, that should have only taken about ten minutes or so.

Next ten minutes will be to set up and configure Jekyll Bootstrap. Following the instructions from the Bootstrap site, enter the following commands in your preferred projects directory (I like ~/Projects/ myself):

$ git clone https://github.com/plusjade/jekyll-bootstrap.git your-username.github.com
$ cd your-username.github.com
$ git remote set-url origin git@github.com:your-username/your-username.github.com.git
$ git push origin master

You should now be able to go to https://your-username.github.com/ and see the Jekyll Bootstrap demo live, as well as run rake preview and visit http://localhost:4000/ to see it hosted on your machine.

Configuration

If you’d like to use a theme, now would be a good time to install one. Visit the Theme browser and choose one - you can adjust it later, of course, but it’s just a starting point. Click “Install Theme” at the bottom left to be given a commandline to install the theme to your project. You should be given the choice to switch to that theme immediately; you can switch later with rake theme:switch theme-name if you wish.

Now let’s do some configuration. index.md describes a few, but you’ll really want to investigate _config.yml for the full list. At the least, you’ll want to check out the following:

title
tagline
author
production_url
JB
- comments
- analytics

For the Comments and Analytics sections, you’ll want to set yourself up some external services. That’ll be the next ten minutes, unless you’ve done this before. First, head to Disqus and create an account for yourself there, and register your site. Add your site shortname to the configuration. Next, head to Google Analytics and sign up if you haven’t already. Create a new account to track your website. You should recieve a tracking code that looks something like UA-12345-1. Add that to the analytics section.

Your blog should be set up, at least initially. Commit and push your repository and check it online. Time to start your first post!

Next Steps

Jekyll Bootstrap comes with a sample post in the _posts/core-samples directory. You’ll want to read this, as it contains useful information on how the Jekyll engine works. After you’ve read through it, delete the entire core-samples directory as you’ll want to start your blog fresh. You can start the first post from the commandline; for example, this is the command I used to create this post: rake post title="Deploying a blog to Github in 30 minutes or less"

If you’ve been chugging along, you should reach this point in just around 30 minutes. Now, comes the hard part: What do you write about? Unfortunately, I can’t help you there.