We’re sorry, but something went wrong!

I’ve been seeing some strange behaviour on the development environment for On the Game recently. I’ve just spent an hour combing through every line of code that varies from a standard Rails app, and I’ve finally found the issue. I’m putting it here for posterity.

Regardless of my configuration, Rails was always displaying the production page for 500 errors (public/500.html) even in development mode.

I poked around for a while and eventually found it to be this:

I’d redefined Enumerable#sum somewhere (don’t ask!), and my implementation didn’t handle arrays of strings. That’s it, that’s why the detailed error page wasn’t being shown in development.

Ends up, Enumerable#sum is used by the development error page, and when something on that error page itself raises an error Rails will just fall back and show the 500.html and not log anything.

Moral of the story: If you’re seeing this behaviour, check you haven’t (badly) monkey patched something that the error page is using.

I remember years ago, some friends and I were talking about money and our savings accounts. They were flabbergasted at how I, a 19 year old at the time, were able to have nearly £10,000 saved (sadly which I’ve since spent!). I explained that it’s easy to save money if you do it slowly and consistently. £50 a week over the course of three years adds up. Obvious, right?

You don’t sit down and decide “I’m going to save £10,000” and then promptly spend one month working yourself to death to put away the whole amount in one go. It’d be nice to have the option to do that occasionally, but that’s not how most of us work. The same applies to learning.

You don’t need to read a 300 page book to learn something. Read a blog post (or an article, mailing list thread, commit discussion). One. Pick a subject and read a single article on it. Do this once a week, every week. That’s it, that’s my secret to learning.

Knowledge isn’t a substitute for experience, but it’ll certainly get you a lot further down the road, faster, than you would get without it.

Take Ruby as the typical example. Ruby on Rails has been around for 6 years now (and Ruby for nearly 15, but not visibly), if you’d have read one article on Ruby a week, you’d have read 312 by now. Three hundred and twelve. Combine that with the occasional Sunday afternoon playing around and I’m confident you’d be pretty proficient by now.

• Javascript is around 15 years old.
• Haskell, 20 years.
• Erlang, 25 years.
• Python, 20 years.
• Clojure, 4 years. Scheme? 36 years.

Of course, we’ve not all been trying to learn those languages for as long as they’ve existed. Consider this though, in one year you could be proficient in a new language if you commit to just 15 minutes a week, or you could be in exactly the same place you are now still unable to find time to learn anything.

How do you eat an elephant? One bite at a time.

Addendum: but everything moves so fast!

No, it doesn’t. It just feels like that from the inside.

Learn something fundamental and your knowledge will transcend trends. Learning a new language is a great way to do that whilst also feeling cool and trendy. Ruby or Python will help you understand dynamic languages, Scala will make you appreciate how powerful and unobtrusive static languages can be, and Clojure will introduce the code-as-data mindset. All those things will be useful beyond the scope of the language you’re learning.

Stealth edit: Fixed my amazing saving ability.

As one of the last things on my to-do list for Inca, licensing has been delayed and delayed; finally, with me making the announcement on Twitter the other day I felt I should probably get it sorted. I was going to write a nice long post about my thoughts on anti-piracy measures, but the Balsamiq team have already done it nicely.

Instead, here’s a guide to using Rhino Licensing. Your mileage may vary.

Rhino Licensing is an open-source licensing framework by Ayende Rahien, and it grew out of his frustration with other license providers while creating NHibernate Profiler.

Rhino Licensing uses asymmetric encryption–also known as public-key cryptography–specifically the RSA algorithm. In cryptography, asymmetric means there are two parts to each key, one public and one private. You encrypt a value using the one key, and it can only be decrypted using the other key. In the case of license key generation, we store our private key on the server (and never tell anyone it!), and distribute the public key with our application. When the user receives a license key, the application is able to verify that it came from us by using the public key. If someone tries to use a license key they’ve generated themselves, it wouldn’t work unless they had our exact private key.

Other systems that use asymmetric encryption include SSH, SSL, PGP, and among others, Git uses asymmetric encryption for its security due to it using SSH.

The format of the license that Rhino Licensing generates is an XML document, plain and simple. By default, it includes the user’s name, an expiration date, the type of license (trial, standard, floating, etc…), and most importantly the cryptographic signature. Below is an example Rhino Licensing generated license.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

<?xml version="1.0" encoding="utf-8"?>
<license id="ae4c05b5-c188-47f8-852f-b4e5375621f7"
    expiration="2011-01-01T00:00:00.0000000" type="Standard">
  <name>Bilbo</name>
  <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
    <SignedInfo>
      <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />
      <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />

      <Reference URI="">
        <Transforms>
          <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
        </Transforms>
        <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
        <DigestValue>sKDT7gzgedzmh1AMxxLbfcF1Hsw=</DigestValue>
      </Reference>
    </SignedInfo>
    <SignatureValue>
        SfkvCGv1+EdLTvaROv27ymDumS0y02fPANTVhr0Yxd/
        AxxVH0q0BQ6w8Ou5L7gyLYLvnSckgjhrGnGpiifdvbg==
    </SignatureValue>
  </Signature>
</license>

What’s a signature?

A cryptographic signature is a string of bytes used to aid in verification of the source of a document. In most cases–and in the case of Rhino Licensing–the signature is generated by hashing the content of the file using SHA1 (or another suitable hashing algorithm), and encrypting that hash using the private key. The resulting string of bytes is the signature.

When the client receives a file with a signature, it creates a hash of the file (sans-signature) and compares that hash to the decrypted value of the signature. Baring in mind that the signature is an encrypted hash of the file, if either of the public or private keys were invalid or the file had been tampered with, then the decrypted string would not match the hash of the file. When the client generated hash and the decrypted signature match, you can be confident the sender of the message is who you think it is.

The great part about using the hash of the document as the signature is that if the user tampers with the license–such as changing the expiration date or the licensee name–the signature will no longer match the hash the client generates, and BAM, instant invalid license.

One particular aspect I like with this approach is that the licensee name is clearly visible in the license. This simple act can be quite dissuasive when it comes to piracy; after all, who would want their name visible on all the torrent websites out there?

Enough with the waffle, let’s start using Rhino Licensing.

Create your key

The first thing we need to do is generate a public/private key pair for us to use in our license generation. Rhino Licensing uses the RSACryptoServiceProvider for it’s keys, so we can use that ourselves to generate our keys. One of the simplest ways to do that is to knock up a really quick console application.

1
2
3
4
5
6
7
8
9
10
11
12
13

class Program
{
  static void Main(string[] args)
  {
    var rsa = new RSACryptoServiceProvider(1024);

    File.WriteAllText("publicKey.xml", rsa.ToXmlString(false));
    File.WriteAllText("privateKey.xml", rsa.ToXmlString(true));

    Console.WriteLine("Done");
    Console.ReadKey();
  }
}

That program will generate a new key for you and write out the public and private parts to two separate XML files (publicKey.xml and privateKey.xml). Keep these two files handy!

You will probably want to change the 1024 value in the RSACryptoServiceProvider constructor to something larger. This is the size of the key that will be generated. The larger the better really, but larger numbers require longer to generate.

Update your application

Now we’ll update your application to complain if it doesn’t have a license. In your entry-point for your application you need to assert the license. Before we do that, make sure you’ve got your public key handy from the previous step. Rhino Licensing needs the content of this file, so you can either embed it directly into a constant or as a resource. Secondly, it needs to know where to look for a license that the user will have been given.

Assuming a really simple app, here’s a Program.cs with Rhino Licensing:

1
2
3
4
5
6
7
8
9
10
11
12
13

class Program
{
  static void Main()
  {
    var publicKey = File.ReadAllText("publicKey.xml");

    new LicenseValidator(publicKey, "license.xml")
      .AssertValidLicense();

    Console.WriteLine("Hello");
    Console.ReadKey();
  }
}

If the license.xml file doesn’t exist, or if it’s invalid, Rhino Licensing will throw an exception. Of course, as we haven’t generated a license yet we’ll get an exception. That’s the client done though, so we can move on to our final step now. Once we complete that step, you will be able to just drop a license.xml into the same directory as your application and everything will work as expected.

Create the license generator

We need something to actually generate a license for your users. If you were being all fancy you could do this as a web-service that gets integrated with your payment provider; however, for simplicity’s sake we’ll just create another console application that spits out a license.

Rhino Licensing has a few prerequisites for a license: A name, an id of the license, an expiration date, and a license type. You can also supply a dictionary of custom values, but we wont be using that in this example.

For a really simple license generator all you need is the above for each license, and the private key. We’ll wrap that up in a simple console app which’ll prompt for the required info:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

class Program
{
  static void Main(string[] args)
  {
    var privateKey = File.ReadAllText("privateKey.xml");

    var id = Guid.NewGuid();
    var generator = new LicenseGenerator(private_key);

    Console.Write("Name: ");
    var name = Console.ReadLine();

    Console.Write("Date: ");
    var expirationDate = DateTime.Parse(Console.ReadLine());

    Console.Write("Type: ");
    LicenseType licenseType = (LicenseType)Enum.Parse(typeof(LicenseType), Console.ReadLine());

    // generate the license
    var license = generator.Generate(name, id, expirationDate, licenseType);

    Console.WriteLine();
    Console.WriteLine(license);
    Console.ReadKey();
  }
}

That’s it, you’ve got a license generator. Remember, this will exist behind your firewall, the users will (and must) never see your private key.

If you take the output of this application and save it in a license.xml file in your client, your application should stop throwing license exceptions and run normally! You’ve officially just licensed your app.

What have we just done?

• Created a private key generator, purely for convenience than anything else. We should only need to run this once before we start generating our keys. You could run it once per major release to ensure your 1.0 licenses are never compatible with 2.0.
• Updated our client application to validate the presence and validity of a license (and to explode if there isn’t one).
• Created a “server” to generate licenses for us. This is very primitive but could easily be adapted to a web server. You might want to look at the Rhino Licensing LicensingService before you continue.

My part in all this…

The videos are becoming available at streaming.ndc2010.no, but they’re suffering from bandwidth issues. If you do want to watch the videos, please stream them until the issues are resolved.

Fluent NHibernate

Introduction to Git

The talk was recorded, so if you haven’t already seen it then you can do so at your own leisure.

The video is up on the E-VAN’s Vimeo account, specifically here.

It’s going to be a pretty basic talk on what Git is (and indirectly what DVCS is), and a demo on how to use most of the features you’ll need daily. There might be some advanced talk at the end, depending on how well I time things.

If you’ve already used Git (successfully), then this talk won’t really be for you; unless you just want to listen to me ramble for an hour and an half.

Looking forward to “seeing” you there. Now, I best finish reading that “Getting started with Git” book I’ve had lying around for months.

• You deal with multiples of repositories, not a single central repository
• Updates come from a remote repository, and changes are pushed to a remote; none of these repositories have to be the same
• Origin is the canonical name for the repository you cloned from
• Upstream is the canonical name for the original project repository you forked from

General pushing and pulling

Pushing your changes to a remote: git push remote_name

Pulling changes from a remote: git pull remote_name

Or if you want to rebase:

git fetch remote_name
git rebase remote_name/branch

You can change your branch.autosetuprebase to always, to make this the default git pull behaviour.

That’s all there is to moving commits around in Git repositories. Any other operations you perform are all combinations of the above.

Github — personal repositories

When you’re dealing directly with Github, on a personal project or as the project owner, your repositories will look like this:

To push and pull changes between your local and your github repositories, just issue the push and pull commands with the origin remote:

git push origin
git pull origin

You can set the defaults for these commands too, so the origin isn’t even necessary in a lot of cases.

Github — receiving contributions

As a project owner, you’ll sometimes have to deal with contributions from other people. Each contributor will have their own github repository, and they’ll issue you with a pull request.

There’s no direct link to push between these two repositories; they’re unmanned. To manage changes from contributors, you need to involve your local repository.

You can think of this as taking the shape of a V.

You need to register their github repository as a remote on your local, pull in their changes, merge them, and push them up to your github. This can be done as follows:

1
2
3

git remote add contributor contributor_repository.git
git pull contributor branch
git push

Github — providing contributions

Do exactly as you would your own personal project. Local changes, pushed up to your github fork; then issue a pull request. That’s all there is to it.

Github — the big picture

Here’s how to imagine the whole process, think of it as an N shape.

On the left is the contributor, and the right is the project. Flow goes from bottom left, along the lines to the top right.

1. Contributor makes a commit in their local repository
2. Contributor pushes that commit to their github
3. Contributor issues a pull request to the project
4. Project lead pulls the contributor’s change into their local repository
5. Project lead pushes the change up to the project github

That’s as complicated as it gets.

MSpec is awesome, I think it’s praised by myself and others enough for that particular point to not need any expansion; however, there is a particular feature I would like to highlight that hasn’t really got a lot of press: behaviours.

Behaviours define reusable specs that encapsulate a particular set of, you guessed it, behaviours; you’re then able to include these specs in any context that exhibits a particular behaviour.

Lets go with the cliche’d Vehicle example. Given an IVehicle interface, with Car and Motorbike implementations; these all expose a StartEngine method and some properties reflecting the state of the vehicle. We’ll start the engine and verify that it is actually started, whether it’s got anything on the rev counter, and whether it’s killing our planet in the process (zing!).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

public interface IVehicle
{
  void StartEngine();
  bool IsEngineRunning { get; }
  bool IsPolluting { get; }
  int RevCount { get; }
}

public class Car : IVehicle
{
  public bool IsEngineRunning { get; private set; }

  public void StartEngine()
  {
    // use your imagination...
  }
}

public class Motorbike : IVehicle
{
  public bool IsEngineRunning { get; private set; }

  public void StartEngine()
  {
    // use your imagination...
  }
}

Those are our classes, if rather contrived, but they’ll do. Now what we need to do is write some specs for them.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

public class when_a_car_is_started
{
  Establish context = () =>
    vehicle = new Car();

  Because of = () =>
    vehicle.StartEngine();

  It should_have_a_running_engine = () =>
    vehicle.IsEngineRunning.ShouldBeTrue();

  It should_be_polluting_the_atmosphere = () =>
    vehicle.IsPolluting.ShouldBeTrue();

  It should_be_idling = () =>
    vehicle.RevCount.ShouldBeBetween(0, 1000);

  static Car vehicle;
}

public class when_a_motorbike_is_started
{
  Establish context = () =>
    vehicle = new Motorbike();

  Because of = () =>
    vehicle.StartEngine();

  It should_have_a_running_engine = () =>
    vehicle.IsEngineRunning.ShouldBeTrue();

  It should_have_a_running_engine = () =>
    vehicle.IsEngineRunning.ShouldBeTrue();

  It should_be_polluting_the_atmosphere = () =>
    vehicle.IsPolluting.ShouldBeTrue();

  It should_be_idling = () =>
    vehicle.RevCount.ShouldBeBetween(0, 1000);

  static Motorbike vehicle;
}

Those are our specs, there’s not much in there but already you can see that we’ve got duplication. Our two contexts contain identical specs, they’re the same in what they’re verifying, the only difference is the vehicle instance. This is where behaviours can come in handy.

With behaviours we can extract the specs and make them reusable. Lets do that.

Create a class for your behaviour and adorn it with the Behaviors attribute — this ensures MSpec recognises your class as a behaviour definition and not just any old class — then move your specs into it.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

[Behaviors]
public class VehicleThatHasBeenStartedBehaviors
{
  protected static IVehicle vehicle;

  It should_have_a_running_engine = () =>
    vehicle.IsEngineRunning.ShouldBeTrue();

  It should_have_a_running_engine = () =>
    vehicle.IsEngineRunning.ShouldBeTrue();

  It should_be_polluting_the_atmosphere = () =>
    vehicle.IsPolluting.ShouldBeTrue();

  It should_be_idling = () =>
    vehicle.RevCount.ShouldBeBetween(0, 1000);
}

We’ve now got our specs in the behaviour, and have defined a field for the vehicle instance itself (it won’t compile otherwise). This is our behaviour complete, it defines a set of specifications that verify that a particular behaviour.

Lets hook that behaviour into our contexts from before:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

public class when_a_car_is_started
{
  Establish context = () =>
    vehicle = new Car();

  Because of = () =>
    vehicle.StartEngine();

  Behaves_like<VehicleThatHasBeenStartedBehaviors> a_started_vehicle;

  protected static Car vehicle;
}

public class when_a_motorbike_is_started
{
  Establish context = () =>
    vehicle = new Motorbike();

  Because of = () =>
    vehicle.StartEngine();

  Behaves_like<VehicleThatHasBeenStartedBehaviors> a_started_vehicle;

  protected static Motorbike vehicle;
}

We’ve now put to use the Behaves_like feature, which references our behaviour class and imports the specs into the current context. Now when you run your specs, the specs from our behaviour are imported and run in each context. We don’t need to assign anything to that field, just defining it is enough; the name you choose for the field is what’s used by MSpec as the description for what your class is behaving like. In our case this is translated roughly to “when a motorbike is started it behaves like a started vehicle”.

There are a couple of things you need to be aware of to get this to work: your fields must be protected, both in the behaviour and the contexts; and the fields must have identical names. If you don’t get these two correct your behaviour won’t be hooked up properly. It’s also good to know that the fields do not need to have the same type, as long as the value from your context is assignable to the field in the behaviour then you’re good; this is key to defining reusable specs for classes that share a sub-set of functionality.

In short, behaviours are an excellent way of creating reusable specs for shared functionality, without the need to create complex inheritance structures. It’s not a feature you should use lightly, as it can greatly reduce the readability of your specs, but it is a good feature if you’ve got a budding spec explosion nightmare on your hands.

Here we go again, explaining the internals of Git with the intention of helping you understand what you’re doing day-to-day. Last time I covered branches, HEAD, and fast-forwarding. Today we’ll dive into the guts of merging and rebasing.

Merging branches

You’ve probably merged before. You do it when you want the changes from one branch in another. The principal is the same in Git as it is most other source control systems, but the implementation differs.

Given the following commit structure, consisting of two branches created from the same commit, each with two commits after the branching occurred.

When these two branches are merged together, this is the structure that results:

The top-most commit, the red one, is a new commit made by the merge; the merge commit is what reminds Git that a merge occurred next time it’s showing the history. This commit is special, as it contains multiple parent’s in it’s meta-data; these multiple parent’s allow Git to follow the two trees of commits that constituted the branches that were merged.

One difference in how Git handles merges compared to many other SCMs is that it preserves the commits that were made in both branches. In other systems merges are often represented as a single commit containing the squashed contents of all the commits that were made in the branch being merged in. Git doesn’t do this (by default, you can tell it to if you want), and therefore preserves all the commits just as they were made; this is quite nice, as it proves incredibly useful to be able to track the origin of changes beyond the point of a merge.

When you merge two branches, it’s interesting to know that none of the commits are altered in the process. Just bare this in mind for now, I’ll explain why this is good to know later.

After a merge, if you were to view the history, you’d see it shown like the previous example, commits in chronological order; the feature branch commits are interspersed between the master commits.

Yet no commits have been altered in the merge, so how are the commits in a different order? Well, they’re not, Git’s just showing you it in the order you expect it to be in. Internally the structure is still as below:

The merge commit instructs Git to walk the two trees while building the history, and it just displays the results in chronological order. This makes more sense if you recall that Git commits don’t hold differences like other SCM systems, instead they each contain a snapshot of the complete repository; while in another SCM the ordering of commits is vital — otherwise the diffs wouldn’t build a valid file — Git is able to infer order without affecting the repository contents.

Looking at it in commit order, you can quite easily see how Git flattens the history to be perceived as linear without ever having to touch any of the original commits.

What happens if there’s a merge conflict?

We’ve all dealt with conflicts in merging before. They typically happen when changes are made to the same file in two branches, in a way that cannot be easily merged (two people edit the same line, for example).

Git’s commit’s are immutable though, so how are the changes that you need to make to resolve these conflicts saved? Simple. The merge commit is a regular commit with some extra meta-data, and so it capable of containing changes itself; merge conflict changes are stored in the merge commit. Again, no changes necessary to the original commits.

Git objects, immutability, and rewriting history

A Git repository is comprised of objects. A file is a blob object with a name attached to it; if you have two files with the same content, that’s just two names to a single blob. A directory is a tree object, which is comprised of other trees and blobs. A commit is an object that references a tree object, which is the state of the repository at the time of committing.

To read more about git objects, I’d definitely recommend you read the Git community book.

Git objects are immutable. To change an object after it’s been created is impossible, you have to recreate the object with any changes made. Even operations that seem to modify objects actually don’t; commit --amend is a typical example, that deletes and re-creates the commit rather than actually amending it.

I mentioned that merges don’t rewrite history, and that it’s a good thing. Now I’ll explain why. When you rewrite history, you do so by making changes to commits that ripple up the commit tree; when this happens, it can cause complications when others merge from you. Given a series of commits, like so:

You then share these commits with another user.

John now has Michael’s commits in his repository; however, Michael notices he’s made a typo in the first commit message, so he amends the commit message. The change in the message requires the commit be recreated. With that first commit recreated, the second commit now has an invalid parent reference, so that commit has to be recreated with the new reference; this recreation ripples it’s way up the tree, recreating each commit with a new parent. Michael has completely rewritten his tree’s history.

Notice all the commit hashes have changed in Michael’s repository, and John’s now don’t match. If Michael was then to make a new commit to his repository, and John tried to merge that change into his repository, Git would get very upset because the new commit would reference a commit that doesn’t exist in John’s repository.

The golden rule is: rewriting history is fine as long as the commits that will be affected haven’t been made public.

Rebasing

The purpose of a rebase is the same as a merge, to bring two tree’s of commits together. It differs in it’s approach. Rebasing is a seriously sharp tool. Very powerful, but pretty easy to cut yourself with it.

When you rebase one branch onto another, Git undoes any changes you’ve made in the target branch, brings it up to date with the changes made in the source branch, then replays your commits on top. This sounds quite strange, so I’ll go over it step-by-step.

You start with your diverged branches:

If you then rebase feature onto master, Git undoes the changes in master.

The history of both branches is now the same, master has been updated to reflect feature; the new commits that were made in master are now detached, floating in the repository without anything referencing them.

The next step is to replay the master commits onto the new structure. This is done one-by-one, and can sometimes result in conflicts that will need to be handled like any merge.

After replaying the repository will look like this:

The master branch commits are now on the top of the stack, after the commits from the feature branch.

You should recall that commits are immutable, and for changes to be made commits need to be recreated. A rebase is a destructive operation, as it has to rewrite commits to be able to work. In this case, the commits from feature have been unaffected, but the master commits have been assigned new parents (and thus rewritten). What’s also noticeable is there’s a lack of a merge commit, which isn’t needed because the commits have been integrated into the tree; any conflicts are stored in the amended commits, rather than in a merge commit.

The rewriting of commits in a rebase is what makes it a dangerous operation to perform on any branch that has already been pushed to the public (or specifically, that the changes affected by the rebase have already been pushed to the public). A rebase can cause problems upstream, like mentioned in the previous section.

Rebase has it’s place though. If you’re working locally and haven’t yet pushed your changes public, it can be a useful tool. Rebase can be used to pull in changes from upstream in the order that the upstream repository has them, and your local changes (that can be rewritten because you’re the only one with them) can be replayed on-top; this is a really easy way to keep your repository up-to-date with an authoritative source. You can also use Rebase to manage local branches that you don’t necessarily want polluting the history with merge markers.

When to rebase and when to merge?

Merge when you’ve already made changes public, and when you want to indicate that two tree’s have converged. Rebase pretty much any other time.

That’s it for this time. Same deal as last time, if you have anything you’d like me to cover I’ll nail it in the next one.

Lets get some learning done. There are a few questions that keep cropping up when I introduce people to Git, so I thought I’d post some answers as a mini-series of blog posts. I’ll cover some fundamentals, while trying not to retread too much ground that the fantastic Git community book already covers so well. Instead I’m going to talk about things that should help you understand what you and Git are doing day-to-day.

What’s a branch?

I know what you’re thinking. “C’mon, we know what a branch is”. A branch is a copy of a source tree, that’s maintained separately from it’s parent; that’s what we perceive a branch to be, and that’s how we’re used to dealing with them. Sometimes they’re physical copies (VSS and TFS), other times they’re lightweight copies (SVN), but they’re copies non-the-less. Or are they?

Lets look at it a different way. The Git way.

Git works a little differently than most other version control systems. It doesn’t store changes using delta encoding, where complete files are built up by stacking differences contained in each commit. Instead, in Git each commit stores a snapshot of how the repository looked when the commit occurred; a commit also contains a bit of meta-data, author, date, but more importantly a reference to the parent of the commit (the previous commit, usually).

That’s a bit weird, I know, but bare with me.

So what is a branch? Nothing more than a pointer to a commit (with a name). There’s nothing physical about it, nothing is created, moved, copied, nothing. A branch contains no history, and has no idea of what it consists of beyond the reference to a single commit.

Given a stack of commits:

The branch references the newest commit. If you were to make another commit in this branch, the branch’s reference would be updated to point at the new commit.

The history is built up by recursing over the commits through each’s parent.

What’s HEAD?

Now that you know what a branch is, this one is easy. HEAD is a reference to the latest commit in the branch you’re in.

Given these two branches:

If you had master checked out, HEAD would reference e34fa33, the exact same commit that the master branch itself references. If you had feature checked out, HEAD would reference dde3e1. With that in mind, as both HEAD and a branch is just a reference to a commit, it is sometimes said that HEAD points to the current branch you’re on; while this is not strictly true, in most circumstances it’s close enough.

What’s a fast-forward?

A fast-forward is what Git does when you merge or rebase against a branch that is simply ahead the one you have checked-out.

Given the following branch setup:

You’ve got both branches referencing the same commit. They’ve both got exactly the same history. Now commit something to feature.

The master branch is still referencing 7ddac6c, while feature has advanced by two commits. The feature branch can now be considered ahead of master.

It’s now quite easy to see what’ll happen when Git does a fast-forward. It simply updates the master branch to reference the same commit that feature does. No changes are made to the repository itself, as the commits from feature already contain all the necessary changes.

Your repository history would now look like this:

When doesn’t a fast-forward happen?

Fast-forwards don’t happen in situations where changes have been made in the original branch and the new branch.

If you were to merge or rebase feature onto master, Git would be unable to do a fast-forward because the trees have both diverged. Considering Git commits are immutable, there’s no way for Git to get the commits from feature into master without changing their parent references.

For more info on all this object malarky, I’d recommend reading the Git community book.

For those of you that don’t know, Fluent NHibernate is for helping you map entities with NHibernate. It’s based firmly on the practice of convention-over-configuration, and can be used in a mapping-per-class style using our fluent interface, or let our automapper map your entities itself.

This release introduces a few significant changes, and a lot of insignificant ones. You should refer to the 1.0 release notes for an overview of what’s changed.

The wiki has also been upgraded to use different software which should hopefully stop people being blocked, and make it a bit more stable; the upgrade included completely rewriting all of the pages, so don’t anyone say that it’s out of date.

You can get the binaries from the our downloads page, or get the source from the github site.

Special thanks go out to the Fluent NHibernate team, Paul Batum, Hudson Akridge, Andrew Stewart, and Stuart Childs. Each of them has put in time and effort above what was asked of them, and they’ve all felt guilty when not contributing, which is great. Thanks also to all the testers and contributors we’ve had over the months. Specifically Darko Conrad, for finding about 30 separate issues with the release candidiate; Everett Muniz and his subclasses, who now has a test of his own; and Kevin Dente, for deciding to moan about our method names only after months of work and a release candidate. I owe everyone beers if ever I’m in your area.

Fabio Maulo, Ayende, and the rest of the NHibernate team: Thanks for a great tool. NHibernate is a shining example of all that is good in open source in the .Net world.

…and with that, I’m going on holiday.

The debugger evaluates property getters when showing it’s locals and autos windows. While this feature is indispensable in most cases, it plays havoc with our property-with-side-effects. What the debugger does is call the getter to present it’s value in the autos window, at the same time firing our code that has a side-effect. From there you have pretty confusing behavior with code seemingly running itself.

My exception to the rule is mutator properties in a fluent interface. You can often find properties in fluent interfaces that when touched alter the behavior of the next method called.

For example:

1
2
3
4

string value = null;

Is.Null(value)      // returns true
Is.Not.Null(value)  // returns false

The Is class would contain a value tracking whether the next call would be inverted or not, and the Not property would flip that value when called.

Now assume this, you’re using Is.Null(value) and you set a breakpoint on it. Your autos window has expanded Is and shows the Not property, what’s just happened? The debugger has now called Not and altered your state! Undesirable.

DebuggerBrowsable attribute to the rescue; this attribute when used with the DebuggerBrowsableState.Never parameter instructs Visual Studio to never inspect the property you apply it to. Your property won’t appear in the autos or locals window, and if you expand the tree of an instance containing the property it will show up with a Browsing Disabled message; you can then force it to evaluate the property, but at least it doesn’t do it automatically.

1
2
3
4
5
6
7
8
9
10
11

private bool inverted = true;

[DebuggerBrowsable(DebuggerBrowsableState.Never)]
public Is Not
{
  get
  {
    inverted = !inverted;
    return this;
  }
}

Sticking the DebuggerBrowsable attribute on your Not property prevents the debugger from hitting it and inverting the switch.

So there you go, if your property-with-side-effects is being invoked by the debugger, you can use the DebuggerBrowsableAttribute to prevent it.

By the way, I’m not advocating properties with side-effects…

You can read the release notes on the wiki for more information on what’s changed. There have been a lot of small breaking changes in the fluent interface, mostly reducing it’s verbosity, and a few larger changes elsewhere. Don’t expect to download this and have it just work, because it won’t; hopefully it shouldn’t be too painful though.

My plan is that this is a very quick turnaround for a release candidate. It’s already undergone some heavy testing from some respected volunteers, but I wanted to get it into the public eye for a week or so before release. Ideally the RTM release won’t differ from this one at all, but we’ll see.

You can find the binaries on our downloads page, and it’s now included in the binary build releases too.

Any questions should be directed to the mailing-list, and issues onto our issue list.

Cross-posted to Los Techies

Git has been gaining a lot of traction lately, and rightly so. I’ve used it for a couple of years now, for all my projects (Fluent NHibernate and Docu being the prominent ones), but something that hasn’t changed is the tag-line of “but Windows support isn’t very good!”. What you quickly learn is that when people say that, they actually mean there isn’t a Visual Studio plug-in or some similar all-singing all-dancing GUI; this is a dire misrepresentation of Git, because it’s tooling on Windows is excellent if your definition of tooling includes the command-line.

It’s something ingrained in Windows developers, they hate the command-line. There’s a very good chance that if you encounter a Windows developer that does enjoy using the command-line it’s because they’ve also worked on another platform or in another environment that encourages command-line use (Rails is a good example). I’ve tried various ways of encouraging people to experiment, but very few work without being able to sit down and just show them something. It’s very much like R# adoption, nobody thinks it’ll speed them up until they see how fast someone else can be.

Back onto Git. If you don’t like what Git does, then that’s fine, but don’t label yourself as Alt.Net or a continuous improver if this sounds like you: “I define myself by choosing the best tool for each situation, but there’s no way you’ll get me using the command-line.” Way to go, oh open-minded one. Try it, you might like it.

The other techies have been posting some great Git posts which can help you get up to speed. I hope to contribute, with less bile, soon.

Fluent NHibernate has seen a flurry of development followed by a complete lack of commits, I figure it’s time to let everyone know what’s going on.

The Short Version

We’re rewriting the internals. We have 100% of tests passing, but still can’t guarantee no regressions. Stuff may break, if it does, tell us. It’ll be worth it.

The Long Version

Once upon a time…

Fluent NHibernate at it’s core is a fluent interface over xml generation. We use the series of methods you call in your mappings to build up an in-memory hbm xml document that we then feed to NHibernate. Slowly, as we’ve started to support more and more of NHibernate’s features, we’ve started to find flaws in our architecture. It amounts to us not having enough separation of concerns; our fluent interface is generating xml, I think most people would say that’s not a good thing. Our xml is being generated too soon in the cycle to allow us to do more clever things that’d improve the user’s experience. That’s where the quiet time comes in.

Paul Batum undertook the task of redesigning the internals of Fluent NHibernate to be something much more scalable. I’ll leave the details out for now (maybe a future post), but it amounts to a intermediary layer being introduced between the fluent interface and the xml generation. We’ve dubbed this the Semantic Model, and it’s that which is now generated by the fluent interface, then later translated into xml. This added abstraction allows us to do things that weren’t possible while we were just generating straight xml.

Whilst you wont see any immediate improvements while everything is being converted, the extra layer allows us to inspect the model before it is converted to xml; this gives us some immense capabilities, such as allowing subclasses to be separate from their parent mapping, create reusable component mappings, improve relationship support etc… We’re pretty much limited only by what we can imagine now, rather than by architectural decisions.

However, we have a dilemma. The semantic-model branch has deviated so much from trunk we’ve got a major merge problem. A merge is pretty much out of the question actually, because there’s barely any commonality between the two streams at all. It was then assumed that the branch would eventually replace trunk (we’d just rename trunk to a tag, then rename the semantic-model branch to trunk), and all we needed to do was get the branch up-to-date with the features of trunk. Little did we realise we were essentially committing to something that I typically oppose, a complete rewrite! I’ve never been in a situation where that’s ever been a good idea, and yet here we are, responsible for our own destiny as it was, and we’d chosen a rewrite!

A few weeks went by with very little work happening. I think we’d all started feeling demoralised by the idea of re-implementing most of the features from trunk using the new design. It was a worthwhile endeavor, definitely, but just very uninteresting. We repeatedly swore that we’d get this done, but all the while we felt less inclined to support trunk because every new feature meant a new feature to port too. We stopped.

At that point Hudson Akridge, our newest contributor, had the balls to tell me that he thought what we were doing felt pretty futile. At that moment I gained a great deal of respect for him, as it’s something that was in the back of my mind for some time but I wasn’t ready to face yet. It was that which got me moving again.

I sat down over a long weekend and took on the mammoth task of merging our rewrite branch and trunk, with the aim of allowing the existing code to exist alongside the new code; this approach, if it worked, would allow us to convert existing features at our own pace while still writing new features for the cleaner codebase. After a lot of unpleasant hacking of nice code, I managed to get all our existing tests passing while utilising the semantic model behind the scenes. Our old code still directly generates xml, which then gets injected into the semantic model via a nasty shortcut. It feels dirty, because I’ve had to comprimise some good code to get it working, but in a way I think that’s a good thing; if code is nasty, we’re all less likely to be content with it. The main goal was achieved though, and that was to allow us to work at our own pace on trunk.

Where we stand now is three branches, trunk, integration, and semantic-model. Over the next day or so I am going to merge integration with trunk, which will mean the semantic model will be in use for new features. From there we can slowly migrate all the original code to use our new semantic model, all the while adding new features using it, then eventually remove the duct-tape that’s holding the legacy code to the new code and dump the old stuff.

This is where I’ll give you a little warning: although we have 100% of tests passing, we don’t have 100% coverage. There may be some regressions that we aren’t aware of. If anyone finds anything broken that was working before, contact us immediately on the mailing list or via the issues list and we’ll correct it. Regressions will be treated with the highest priority over any other work.

That’s it, you now know more about what’s happening with Fluent NHibernate than you ever wanted to. I hope this sheds a little light onto what’s been happening with us, and perhaps why your patch hasn’t been applied as quickly as you would’ve liked.

These are very rough figures, generated with no scientific consistency, some are cumulative and others are based just on the last full month. They’re more just to satisfy my curiosity than to be rigorously accurate.

The reception it’s received has been positive, I never expected it to have a surge of popularity because it’s not that kind of tool, so it hasn’t come as much of a surprise that people haven’t been jumping all over it. Having said that though, I have had some good feedback and already someone has contributed a patch. Additionally, there hasn’t been one question as to why I’ve created it; now this has come as a surprise, I guess I’m not the only one that feels Sandcastle is bloated and overcomplicated. Yay!

I’ve just pushed out some changes to the github repos and released an updated alpha (v0.1.0.2) on the downloads page. The biggest changes so far are the inclusion of events and fields in the parsing, which now means docu has <summary /> support for all documentable members. The rest of the changes are mainly refactorings and some battle-hardening.

I’ve got some more changes and several issues lined up, so keep an eye out.

• Anyone have any tips on generating html docs from XML comments? Used to do it years ago with NDoc ?
• Man, sandcastle is so overly complex ?
• Sandcastle examples don’t even work. This is shit. ?
• Why isn’t sandcastle just a console app that takes a list of dlls and spits out html/chm? What’s with all the batch files and XslTransforms? ?
• @AndrewNStewart Well Sandcastle requires chaining together several calls to 3+ applications before you get anything. ?
• Are these Sandcastle generated MSDN-style API docs actually useful to anyone? ?
• @pollingj It’s a dilemma. I don’t care about API docs, but people seem to want it, but I’m reluctant to generate msdn-like shit. Dilemma. ?

So as you can see, dilemma. People want API documentation (for Fluent NHibernate specifically), but I don’t want to associate myself with the awful MSDN-style documentation that’s produced by Sandcastle.

Before you get all hot under the collar, if you like Sandcastle, or you like MSDN-style documentation, leave now. Use what works for you, it doesn’t work for me so I’m not using it, but I don’t want to stop you using it.

I realise the market for this tool is probably pretty small, but it’s useful to me so it might be useful to you.

Introducing docu, the simple documentation generator for .Net!

Docu is a tool that produces an html site (or rather, a collection of html pages) from the doc-comments you include in your code. Given an assembly and the Visual Studio produced XML of the comments, docu will produce a completely static collection of pages that you can publish anywhere you like. You run it through one command-line tool, with one parameter. That’s it, nothing complicated.

docu your-assembly.dll

You can see an example of the default style that’s provided in the Fluent NHibernate API docs (the colour scheme has been modified, but everything else is default).

Docu is completely stand alone, no GAC deployed assemblies, no hard-coded paths, no nothing. This makes it trivial to use docu in your CI process for building up-to-the-second API docs for publishing or downloading.

The templates that docu uses are created with the Spark view engine which means you have all the power of C# and it’s templating language at your finger-tips. If you’re particularly picky about appearance (like I am) then you can completely rewrite the templates to your heart’s content. There’s no imposed structure or style, it’s all customisable through the templates. You can read more about customising templates on the site: customising templates.

An interesting little feature of the templating system is special names for directories and files, for example if you name a template !namespace.spark, a html page will be produced for a each namespace in your assembly using that template. This allows you to do things like create a directory for each namespace, with a page for each type in that namespace inside. Pretty powerful!

The codebase is reasonably well structured, but the code itself is a bit untidy. Luckily it’s covered by nearly 200 unit tests (so far) and i’ll be leveraging them to improve the code quality over time. You can checkout the code from the docu github repo.

It’s early days yet, there’s very little customisation of the documentation process (the part that actually finds the types and members to document), and not all comment types are supported yet; however, it’s used for Fluent NHibernate and works pretty well. It’s only Alpha right now, so you shouldn’t expect the world.

So if this kind-of thing interests you, go have a read of the docu website and let me know how it works out for you.