jekyll 8 comments suggest edit

Well this is a bit embarrassing.

I recently migrated my blog to Jekyll and subsequently wrote about my painstaking work to preserve my URLs.

But after the migration, despite all my efforts, I faced an onslaught of reports of broken URLs. So what happened?

Broken glass by Tiago Pádua CC-BY-2.0

Well it’s silly. The program I wrote to migrate my posts to Jekyll had a subtle flaw. In order to verify that my URL would be correct, it made a web request to my old blog (which was still up at the time) using the generated file name.

This was how I verified that the Jekyll URL would be correct. The problem is that Subtext had this stupid feature where the date part of the URL didn’t matter so much. It only cared about the slug at the end of the URL.

Thus requests for the following two URLs would receive the same content:

  • https://haacked.com/archive/0001/01/01/some-post.aspx
  • https://haacked.com/archive/2013/11/21/some-post.aspx

Picard Face Palm

This “feature” masked a timezone bug in my exporter that was causing many posts to generate the wrong date. Unfortunately, my export script had no idea these were bad URLs.

Fixing it!

So how’d I fix it? First, I updated my 404 page with information about the problem and where to report the missing file. You can set a 404 page by adding a 404.html file at the root of your Jekyll repository. GitHub pages will serve this file in the case of a 404 error.

I then panicked and started fixing errors by hand until my helpful colleagues Ben Balter and Joel Glovier reminded me to try Google Analytics and Google Webmaster Tools.

If you haven’t set up Google Webmaster Tools for your website, you really should. There are some great tools in there including the ability to export a CSV file containing 404 errors.

So I did that and wrote a new program, Jekyll URL Fixer, to examine the 404s and look for the corresponding Jekyll post files. I then renamed the affected files and updated the YAML front matter with the correct date.

Hopefully this fixes most of my bad URLs. Of course, if anyone linked to the broken URL in the interim, they’re kind of hosed in that regard.

I apologize for the inconvenience if you couldn’t find the content you were looking for and am happy to refund anyone’s subscription fees to Haacked.com (up to a maximum of $0.00 per person).

jekyll 6 comments suggest edit

In my last post, I wrote about preserving URLs when migrating to Jekyll. In this post, show how to preserve your Disqus comments.

This ended up being a little bit tricker. By default, disqus stores comments keyed by a URL. So if you people create Disqus comments at http://example.com/foo.aspx, you need to preserve that exact URL in order for those comments to keep showing up.

In my last post, I showed how to preserve such a URL, but it’s not quite exact. With Jekyll, I can get a request to http://example.com/foo.aspx to redirect to http://example.com/foo.aspx/. Note that trailing slash. To Disqus, these are two different URLs and thus my comments for that page would not load anymore.

Fortunately, Disqus allows you to set a Disqus Identifier that it uses to look up a page’s comment thread. For example, if you view source on a migrated post of mine, you’ll see something like this:

<script type="text/javascript">
  var disqus_shortname = 'haacked';
      
  var disqus_identifier = '18902';
  var disqus_url = 'https://haacked.com/archive/2013/10/28/code-review-like-you-mean-it.aspx/';
  
  // ...omitted
</script>

The disqus_identifier can pretty much be any string. Subtext, my old blog engine, set this to the database generated ID of the blog post. So to keep my post comments, I just needed to preserve that as I migrated over to Jekyll.

So what I did was add my own field to my migrated Jekyll posts. You can see an example by clicking edit on one of the older posts. Here’s the Yaml frontmatter for that post.

---
layout: post
title: "Code Review Like You Mean It"
date: 2013-10-28 -0800
comments: true
disqus_identifier: 18902
categories: [open source,github,code]
---

This adds a new disqus_identifier field that can be accessed in the Jekyll templates. Unfortunately, the default templates you’ll find in the wild (such as the Octopress ones) won’t know what to do with this. So I updated the disqus.html Jekyll template include that comes with most templates. You can see the full source in this gist.

But here’s the gist of that gist:

var disqus_identifier = '{% if page.disqus_identifier %}{{ page.disqus_identifier}}{% else %}{{ site.url }}{{ page.url }}{% endif %}';
var disqus_url = '{{ site.url }}{{ page.url }}';

If your current blog engine doesn’t explicitly set a disqus_identifier, the identifier is the exact URL where the comments are hosted. So you could set the disqus_identifier to that for your old posts and leave it empty for your new ones.

jekyll 10 comments suggest edit

In my last post I wrote about migrating my blog to Jekyll and GitHub Pages. Travis Illig, a long time Subtext user asked me the following question:

The only thing I haven’t really figured out is how to nicely handle the redirect from old URLs (/archive/blah/something.aspx) to the new ones without extensions (/archive/blah/something/). I’ve seen some meta redirect stuff combined with JavaScript but… UGH.

UGH Indeed! I decided not to bother with changing my existing URLs to be extensionless. Instead, I focused on preserving my existing permalinks by structuring my posts such that they preserved their existing URLs.

How did I do this? My old URLs have an ASP.NET .aspx extension. Surely, GitHub Pages won’t serve up ASPX files. This is true. But what it will serve up is a folder that just happens to have a name that ends with “.aspx”.

The trick is in how I named the markdown files for my old posts. For example, check out a recent post: 2013-11-20-declare-dont-tell.aspx.markdown

Jekyll takes the part after the date and before the .markdown extension and uses that as the post’s URL slug. In this case, the “slug” is declare-dont-tell.aspx.

The way it handles extensionless URLs is to create a folder with the slug name (in this case a folder named declare-dont-tell.aspx) and creates the blog post as a file named index.html in that folder. Simple.

Thus the URL for that blog post is https://haacked.com/archive/2013/11/20/declare-dont-tell.aspx/. But here’s the beautiful part. GitHub Pages doesn’t require that trailing slash. So if you make a request for https://haacked.com/archive/2013/11/20/declare-dont-tell.aspx, everything still works! GitHub simply redirects you to the version with the trailing slash.

Meanwhile, all my new posts from this point on will have a nice clean extensionless slug without breaking any permalinks for my old posts.

blogging jekyll 33 comments suggest edit

The older I get, the less I want to worry about hosting my own website. Perhaps this is the real reason for the rise of cloud hosting. All of us old fogeys became too lazy to manage our own infrastructure.

For example, a while back my blog went down and as I frantically tried to fix it, I received this helpful piece of advice from Zach Holman.

@haacked the ops team gets paged when http://zachholman.com is down. You still have a lot to learn, buddy.

Indeed. Always be learning.

What Zach refers to is the fact that his blog is hosted as a GitHub Pages repository. So when his blog goes down (ostensibly because GitHub Pages is down), the amazing superheroes of the GitHub operations team jumps into action to save the day. These folks are amazing. Why not benefit from their expertise?

So I did.

One of the beautiful things about GitHub Pages is that it supports Jekyll, a simple blog aware static site generator.

If you can see this blog post, then the transition of my blog over to Jekyll is complete and (mostly) successful. The GitHub repository for this blog is located at https://github.com/haacked/haacked.com. Let me know if you find any issues. Or better yet, click that edit button and send me a pull request!

Screen grab from the 1931 movie Dr. Jekyll and Mr. Hide public domain

There are two main approaches you can take with Jekyll. In one approach, you can use something like Octopress to generate your site locally and then deploy the locally generated output to a gh-pages branch. Octopress has a nice set of themes (my new design is based off of the Greyshade theme) and plugins you can take advantage of with this approach. The downside of that approach is you can’t publish a blog post solely through GitHub.com the website.

Another approach is to use raw Jekyll with GitHub pages and let GitHub Pages generate your site when your content changes. The downside of this approach is that for security reasons, you have a very limited set of Jekyll plugins at your disposal. Even so, there’s quite a lot you can do. My blog is using this approach.

This allows me to create and edit blog posts directly from the web interface. For example, every blog post has an “edit” link. If you click on that, it’ll fork my blog and take you to an edit page for that blog post. So if you’re a kind soul, you could fix a typo and send me a pull request and I can update my blog simply by clicking the Merge button.

Local Jekyll

Even with this latter approach, I found it useful to have Jekyll running locally on my Windows machine in order to test things out. I just followed the helpful instructions on this GitHub Help page. If you are on Windows, you will inevitably run into some weird UTF Encoding issue. The solution is fortunately very easy.

Migrating from Subtext

Previously, I hosted my blog using Subtext, a database driven ASP.NET application. In migrating to Jekyll, I decided to go all out and convert all of my existing blog posts into Markdown. I wrote a hackish ugly console application, Subtext Jekyll Exporter, to grab all the blog post records from my existing blog database.

The app then shells out to Pandoc to convert the HTML for each post into Markdown. This isn’t super fast, but it’s a one time only operation.

If you have a blog stored in a database, you can probably modify the Subtext Jekyll Exporter to create the markdown post files for your Jekyll blog. I apologize for the ugliness of the code, but I have no plans to maintain it as it’s done its job for me.

The Future of Subtext

It’s with heavy heart that I admit publicly what everyone has known for a while. Subtext is done. None of the main contributors, myself included, have made a commit in a long while.

I don’t say dead because the source code is available on GitHub under a permissive open source license. So anyone can take the code and continue to work on it if necessary. But the truth is, there are much better blog engines out there.

I started Subtext with high hopes eight years ago. Despite a valiant effort to tame the code, what I learned in that time was that I should have started from scratch.

I was heavily influenced by this blog post from Joel Spolksy, Things You Should Never Do.

Well, yes. They did. They did it by making the single worst strategic mistake that any software company can make:

They decided to rewrite the code from scratch.

Perhaps it is a strategic mistake for a software company, but I’m not so sure the same rules apply to an open source project done in your spare time.

So much time and effort was sacrificed at the altar of backwards compatibility as we moved mountains to make the migration from previous versions to next continue to work while trying to refactor as much as possible. All that time dealing with the past was time not spent on innovative new features. I was proud of the engineering we did to make migrations work as well as they did, but I’m sad I never got to implement some of the big ideas I had.

Despite the crap ton of hours I put into it, so much so that it strained my relationship at times, I don’t regret the experience at all. Working on Subtext opened so many doors for me and sparked many lifelong friendships.

So long Subtext. I’ll miss that little submarine.

code, rx 0 comments suggest edit

Judging by the reaction to my Death to the If statement where I talked about the benefits of declarative code and reducing control statements, not everyone is on board with this concept. That’s fine, I don’t lose sleep over people being wrong.

Photo by Grégoire Lannoy CC BY 2.0

My suspicion is that the reason people don’t have the “aha! moment” is because examples of “declarative” code are too simple. This is understandable because we’re trying to get a concept across, not write the War and Peace of code. A large example becomes unwieldy to describe.

A while back, I tried to tackle this with an example using Reactive Extensions. Imagine the code you would write to handle both the resize and relocation of a window, where you want to save the position to disk, but only after a certain interval has passed since the last of either event.

So you resize the window, then before the interval has passed you move the window. And only have you stop moving it and resizing it for this interval, does it save to disk.

Set aside your typical developer bravado and think about what that code looks like in a procedural or object oriented language. You functional reactive programmers can continue to smirk smugly.

The code is going to be a bit gnarly. You will have to write bookkeeping code such as saving the time of the last event so you can check that the duration has passed. This is because you’re telling the computer how to throttle.

With declarative code, you more or less declare what you want. “Hey! Give me a throttle please!” (Just because you are declaring, it doesn’t mean you can’t be polite. I like to add a Please suffix to all my methods). And declarations are much easier to compose together.

This example is one I wrote about in my post Make Async Your Buddy with Reactive Extensions. But I made a mistake in the post. Here’s the code I showed as the end result:

Observable.Merge(
    Observable.FromEventPattern
      <SizeChangedEventHandler, SizeChangedEventArgs>
        (h => SizeChanged += h, h => SizeChanged -= h)
        .Select(e => Unit.Default),
    Observable.FromEventPattern<EventHandler, EventArgs>
        (h => LocationChanged += h, h => LocationChanged -= h)
        .Select(e => Unit.Default)
).Throttle(TimeSpan.FromSeconds(5), RxApp.DeferredScheduler)
.Subscribe(_ => this.SavePlacement());

I’ll give you a second to recover from USBS (Ugly Syntax Blindness Syndrome).

The code isn’t incorrect, but there’s a lot of noise in here due to the boilerplate expressions used to convert an event into an observable sequence of events. I think this detracted from my point.

So today, I realized I should add a couple of really simple extension methods that describe what’s going on and hides the boilerplate.

// Returns an observable sequence of a framework element's
// SizeChanged events.
public static IObservable<EventPattern<SizeChangedEventArgs>> 
    ObserveResize(this FrameworkElement frameworkElement)
{
  return Observable.FromEventPattern
    <SizeChangedEventHandler, SizeChangedEventArgs>(
        h => frameworkElement.SizeChanged += h,
        h => frameworkElement.SizeChanged -= h)
      .Select(ep => ep.EventArgs);
}

// Returns an observable sequence of a window's 
// LocationChanged events.
public static IObservable<EventPattern<EventArgs>> 
    ObserveLocationChanged(this Window window)
{
  return Observable.FromEventPattern<EventHandler, EventArgs>(
      h => window.LocationChanged += h,
      h => window.LocationChanged -= h)
    .Select(ep => ep.EventArgs);
}

This then allows me to rewrite the original code like so:

this.ObserveResize()
  .Merge(this.ObserveLocationChanged())
  .Throttle(TimeSpan.FromSeconds(5), RxApp.MainThreadScheduler)
  .Subscribe(_ => SavePlacement());

That code is much easier to read and understand what’s going on and avoids the plague of USBS (unless you’re a Ruby developer in which case you have a high sensitivity to USBS).

The important part is we don’t have to maintain tricky bookkeeping code. There’s no code here that keeps track of the last time we saw one or the other event. Here, we just declare what we want and Reactive Extensions handles the rest.

This is what I mean by declare, don’t tell. We don’t tell the code how to do its job. We just declare what we need done.

UPDATE: ReactiveUI (RxUI) 5.0 has an assembly Reactive.Events that maps every event to an observable for you! For example:

control.Events()
  .Clicked
  .Subscribe(_ => Console.WriteLine("foo"));

That makes things much easier!

code 0 comments suggest edit

Not long ago I wrote a blog post about how platform restrictions harm .NET. This led to a lot of discussion online and on Twitter. At some point David Kean suggested a more productive approach would be to create a UserVoice issue. So I did and it quickly gathered a lot of votes.

I’m visiting Toronto right now so I’ve been off of the Internet all day and missed all the hubbub when it happened. I found out about it when I logged into Gmail and I saw I had an email that the user voice issue I created was closed. My initial angry knee-jerk reaction was “What?! How could they close this without addressing it?!” as I furiously clicked on the subject to read the email and follow the link to this post.

Bravo!

Serious Kudos to the .NET team for this. It looks like most of the interesting PCL packages are now licensed without platform restrictions. As an example of how this small change sends out ripples of goodness, we can now make Octokit.net depend on portable HttpClient and make Octokit.net itself more cross platform and portable without a huge amount of work.

I’m also excited about the partnership between Microsoft and Xamarin this represents. I do believe C# is a great language for cross-platform development and it’s good to see Microsoft jumping back on board with this. This is a marked change from the situation I wrote about in 2012.

code 0 comments suggest edit

Over the past few years I’ve become more and more interested in functional programming concepts and the power, expressiveness, and elegance they hold.

But you don’t have to abandon your language of choice and wander the desert eating moths and preaching the gospel of F#,  Haskell, or Clojure to enjoy these benefits today!

In his blog post, Unconditional Programming, Michael Feathers ponders how less control structures lead to better code,

Control structures have been around nearly as long as programming but it’s hard for me to see them as more than an annoyance.  Over and over again, I find that better code has fewer if-statements, fewer switches, and fewer loops.  Often this happens because developers are using languages with better abstractions.  They aren’t consciously trying to avoid control structures but they do.

We don’t need to try and kill every if statement, but perhaps the more we do, the better our code becomes.

Msi_if_coverPhoto from wikimedia: Cover of If by the artist Mindless Self Indulgence

He then provides an example in Ruby of a padded “take” method.

…I needed to write a ‘take’ function to take elements from the beginning of an array.  Ruby already has a take function on Enumerable, but I needed to special behavior.  If the number of elements I needed was larger than the number of elements in the array, I needed to pad the remaining space in the resulting array with zeros.

I recommend reading his post. It’s quite interesting. At the risk of spoiling the punch line, here’s the before code which makes use of a conditional…

  def padded_take ary, n
    if n <= ary.length
      ary.take(n)
    else
      ary + [0] * (n - ary.length)
  end
  end

… and here is the after code without the conditional. In this case, he pads the source array with just enough elements as needed and then does the take.

  def pad ary, n
    pad_length = [0, n - ary.length].max
    ary + [0] * pad_length
  end

  def padded_take ary, n
    pad(ary, n).take(n)
  end

I thought it would be interesting to translate the after code to C#. One thing to note about the Ruby code is that it always allocates a new array whether it’s needed or not.

Now, I haven’t done any benchmarks on it so I have no idea if that’s bad or not compared to how often the code is called etc. But it occurred to me that we could use lazy evaluation in C# and completely circumvent the need to allocate a new array while still being expressive and elegant.

I decided to write it as an extension method (I guess that’s similar to a Mixin for you Ruby folks?).

public static IEnumerable<T> PaddedTake<T>(
  this IEnumerable<T> source, int count)
{
  return source
    .Concat(Enumerable.Repeat(default(T), count))
    .Take(count);
}

This code takes advantage of some Linq methods. The important thing to note is that Concat and Repeat are lazily evaluated. That’s why I didn’t need to do any math to figure out the difference in length between the source array and the the take count.

I just passed the total count we want to take to Repeat. Since Repeat is lazy, we could pass in int.MaxValue if we wanted to get all crazy up in here. I just passed in count as it will always be enough and I like to play it safe.

Now my Ruby friends at work might scoff at all those angle brackets and parentheses in the code, but you have to admit that it’s an elegant solution to the original problem.

Here is a test to demonstrate usage and show it works.

var items = new[] {1, 2, 3};

var result = items.PaddedTake(5).ToArray();

Assert.Equal(5, result.Length);
Assert.Equal(1, result[0]);
Assert.Equal(2, result[1]);
Assert.Equal(3, result[2]);
Assert.Equal(0, result[3]);
Assert.Equal(0, result[4]);

I also ran some quick perf tests on it comparing PaddedTake to the built in Take . PaddedTake is a tiny bit slower, but the amount is like the extra light cast by a firefly at noon of a sunny day. The performance of this method is way more affected by the number of elements in the array and the number of elements you are taking. But in my tests, the performance of PaddedTake stays pretty close to Take as we grow the array and the take.

I think it’d be interesting to have a build task that reported back the number of `if` statements and other control structures per line of code and see if you can bring that down over time. In any case, I hope this helps you improve your own code!

open source, code 0 comments suggest edit

Octokit.net targets multiple platforms. This involves a large risk to my sanity. You can see the general approach here in the Octokit directory of our project:

 octokit-projects

Mono gets a project! MonoAndroid gets a project file! Monotuch gets a project file! Everybody gets a project file!

Each of these projects references the same set of .cs files. When I add a file to Octokit.csproj, I have to remember to add that file to the other four project files. As you can imagine, this is easy to forget.

It’s a real pain. So I opened up a feature request on FAKE, the tool we use for our build (more on that later) and asked them for a task that would fail the build if another project file in the same directory was missing a file from the “source” project file. I figured this would be something easy for F# to handle.

The initial response from the maintainer of FAKE, Steffen Forkman, was this:

What you need is a better project system ;-)

Touché!

This problem (along with so many project file merge conflicts) would almost completely go away with file patterns in project files. I’ve been asking for this for a long time (I asked the Visual Studio team for this the day I joined Microsoft, or maybe it was the first month, I don’t recall). There’s a User Voice item requesting this,go vote it up! (Also, go vote up thisplatform restriction issuethat’s affecting Octokit.net as well)

In any case, sorry to say unlimited chocolate fountains don’t exist and I don’t have the project system I want. So let’s deal with it.

A few days later, I get this PR to octokit.net. When I ran the build, I see the following snippet in the build output.

Running build failed.
Error:
System.Exception: Missing files in  D:\Octokit\Octokit-MonoAndroid.csproj:
Clients\OrganizationMembersClient.cs

That’s telling me that somebody forgot to add the class OrganizationMembersClient.cs to the Octokit-MonoAndroid.csproj. Wow! Isn’t open source grand?

A big thanks to Steffen and other members of the FAKE community who pitched in to build a small but very useful feature. In a follow-up post, I’ll write a little bit about why we moved to using FAKE to build Octokit.net.

Update

I opened an issue to take this to the next step. Rather than just verify the project files, I want some way to automatically modify or generate them.

Update 2

FAKE just got even better with the new FixProjects task! For now, we’ve added this as an explicit command.

.\build FixProjects

Over time, we may just integrate this into the Octokit.net build directly.

open source, code, github 0 comments suggest edit

Most developers are aware of the potential pitfalls of premature optimization and premature generalization. At least I hope they are. But what about premature standardization, a close cousin to premature generalization?

It’s human nature. When patterns emerge, they tempt people to drop everything and put together a standard to codify the pattern. After all, everyone benefits from a standard, right? Isn’t it a great way to ensure interoperability?

Yes, standards can be helpful. But to shoehorn a pattern into a standard prematurely can stifle innovation. New advances are often evolutionary. Multiple ideas compete and the best ones (hopefully) gain acceptance over time while the other ideas die out from lack of interest.

Once standardization is in place, people spend so much energy on abiding by the standard rather than experiment with alternative ideas. Those who come up with alternative ideas become mocked for not following “the standard.” This is detrimental.

In his Rules of Standardization, Yaron Goland suggests that before we adopt a standard,

The technology must be very old and very well understood

He proposes twenty years as a good rule of thumb. He also suggests that,

Standardizing the technology must provide greater advantage to the software writing community then keeping the technology incompatible

This is a good rule of thumb to contemplate before one proposes a standard.

Social Standards

So far, I’ve focused on software interoperability standards. Software has a tendency to be a real stickler when it comes to data exchange. If even one bit is out of place, software loses its shit.

For example, if my code sends your code a date formatted as ISO 8601, but your code expects a date in Unix Time, stuffs gonna be broke™.

But social standards are different. By a “social standard” I mean a convention of behavior among people. And the thing about people is we’re pretty damn flexible, Hacker News crowd notwithstanding.

Rather than being enforced by software or specifications, social standards tend to be enforced through the use of encouragement, coercion, and shaming.

Good social standards are not declared so much as they emerge based on what people do already. If people converge on a standard, then it becomes the standard. And it’s only the standard so long as people adopt it.

This reminds me of a quote by W.L. Gore & Associates’ CEO, Terri Kelly on leadership at a non-hierarchical company,

If you call a meeting, and no one shows up, you’re probably not a leader, because no one is willing to follow you.

Standard GitHub issue labels?

I wrote a recent tweet to announce a label that the Octokit team uses to denote low hanging fruit for new contributors,

For those looking to get started with .NET OSS and http://Octokit.net, we tag low hanging fruit as “easy-fix”. https://github.com/octokit/octokit.net/issues?labels=easy-fix

It was not my intention to create a new social standard.

Someone questioned me why we didn’t use the “jump in” label proposed by Nik Molnar,

The idea for a standardized issue label for open source projects came from the two pieces of feedback I consistently hear from would-be contributors:

  1. “I’m not sure where to start with contributing to project X.”
  2. “I’ll try to pick off a bug on the backlog as soon as I’ve acquainted myself enough with the codebase to provide value.” “”

In the comments to that blog post, Glenn Block notes that the ScriptCS project is using the “YOU TAKE IT” label to accomplish the same thing.

About two and a half years earlier, I blogged about the “UpForGrabs” label the NuGet team was using for the same reason.

As you can see, multiple people over time have had the same idea. So the question was raised to me, would I agree that “standardizing” a label to invite contributors might be a good thing?

To rephrase one of Goland’s rule of standardization,

A social standard must provide greater advantage to the software community than just doing your own thing.

This is a prime example of a social standard and in this case, I don’t think it provides a greater advantage than each project doing it’s own thing. At least not yet. If one arises naturally because everyone thinks it’s a great idea, then I’m sold! But I don’t think this is something that can just be declared to be a standard. It requires more experimentation.

I think the real problem is that these labels are just not descriptive enough. One issue I have with Up For Grabs, You Take It,and Jump Inis they seem too focused on giving commands to the potential contributor, “HEY! YOU TAKE IT! WE DON’T WANT IT!”. They’re focused on the relationship of the core team to the issue. I think the labels should describe the issue and not how the core team wants new contributors to interact with the issue.

What makes an issue appeal to a new contributor is different from contributor to contributor. So rather than a generic “UpForGrabs” label, I think a set of labels that are descriptive of the issue make sense. People can then self-select the issues that appeal to them.

For many new contributors, an issue labeled as “easy-fix” is going to appeal to their need to dip their toe into OSS. For others, issues labeled as “docs-and-samples” will fit their abilities better.

So far, I’ve been delighted that several brand new OSS contributors sent us pull requests. It far surpassed my expectations. Of course, I don’t have a control Octokit.net project with the different labels, so I can’t rightly attribute it to the labels. Science doesn’t work that way. Even if we did, I doubt it’s the labels that made much of any difference here.

Again, this is not an attempt to propose a new standard. This is just an approach we’re experimenting with in Octokit.net. If you like this idea, please steal it. If you have a better idea, I’d love to hear it!

github 0 comments suggest edit

Today on the GitHub blog, we announced the first release of Octokit.net.

Octokit is a family of client libraries for the GitHub API. Back in May, we released Octokit libraries for Ruby and Objective-C.

Today we’re releasing the third member of the Octokit family, Octokit.net, the GitHub API toolkit for .NET developers.

octokit-dotnet

GitHub provides a powerful set of tools for developers who build amazing software together. But these tools extend way beyond the website and Git clients.

The GitHub API provides a rich web based way to leverage GitHub.com within your own applications. The Octokit family of libraries makes it easy to call into the API. I can’t wait to see what you build with it.

The Project

Octokit.net is an open source project on GitHub so feel free to contribute with pull requests, issues, etc. You’ll notice that we call it a 0.1.0 release. As of today, it doesn’t implement every API endpoint that GitHub.com supports.

We wanted to make sure that it was in use by a real application so we focused on the endpoints that GitHub for Windows needs. If there’s an endpoint that is not implemented, please do log an issue. Or even better, send a pull request!

Our approach in implementing this library was to avoid being overly speculative. We tried to implement features as we needed them based on developing a real production application.

But now that it’s in the wild, we’re curious to see what other types of applications will need from the library.

Platform and Licensing Details

Octokit.net is licensed under the MIT license.

As of today, Octokit.net requires .NET 4.5. We also have a WinRT library for .NET 4.5 Core. This is because we build on top of HttpClient is not available in .NET 4.0.

There is a Portable HttpClient package that does work for .NET 4.0, but we won’t distribute it because it has platform limitations that are incompatible with our license.

I had hoped that its platform limitations would have been removed by now, but that sadly is not the case. If you’re wondering why that matters, read my post here.

However, if you check the repository out, you’ll notice that there’s a branch named haacked/portable-httpclient. If you only plan to deploy on Windows, you can build that branch yourself and make use of it.

Go Forth And Build!

I’ve had great fun working with my team at GitHub on Octokit.net the past few weeks. I hope you have fun building amazing software that extends GitHub in ways we never imagined. Enjoy!

open source, github, code, code review 0 comments suggest edit

If I had to pick just one feature that embodies GitHub (besides emoji support of course , I’d easily choose the Pull Request (aka PR). According to GitHub’s help docs (emphasis mine),

Pull requests let you tell others about changes you’ve pushed to a GitHub repository. Once a pull request is sent, interested parties can review the set of changes, discuss potential modifications, and even push follow-up commits if necessary.

Some folks are confused by the name “pull request.” Just think of it as a request for the maintainer of the project to “pull” your changes into their repository.

Here’s a screenshot of a pull request for GitHub for Windows where Paul Betts patiently explains why my code might result in the total economic collapse of the world economy.

sample code review

A co-worker code review is a good way to avoid the Danger Zone (slightly NSFW).

Code review is at the heart of the GitHub collaboration model. And for good reason! There’s a rich set of research about the efficacy of code reviews.

In one of my favorite software books, Facts and Fallacies of Software Engineering by Robert Glass, Fact 37 points out,

Rigorous inspections can remove up to 90 percent of errors from a software product before the first test case is run.

And the best part is, that reviews are cost effective!

Furthermore, the same studies show that the cost of inspections is less than the cost of the testing that would be necessary to find the same errors.

One of my other favorite software books, Code Complete by Steve McConnell, points out that,

the average defect detection rate is only 25 percent for unit testing, 35 percent for function testing, and 45 percent for integration testing. In contrast, the average effectiveness of design and code inspections are 55 and 60 percent.

Note that McConnell is referring to evidence for the average effectiveness while Glass refers to evidence for the peak effectiveness.

The best part though, is that Code Review isn’t just useful for finding defects. It’s a great way to spread information about coding standards and conventions to others as well as a great teaching tool. I learn a lot when my peers review my code and I use it as an opportunity to teach others who submit PRs to my projects.

Effective Code Review

You’ll notice that Glass and McConnell use the term “code inspection” and not review. A lot of time, when we think of code review, we think of simply looking the code up and down a bit, making a few terse comments about obvious glaring errors, and then calling it a day.

I know I’ve been guilty of this “drive-by” code review approach. It’s especially easy to do with pull requests.

But what these gentlemen refer to is a much more thorough and rigorous approach to reviewing code. I’ve found that when I do it well, a proper code review is just as intense and mentally taxing as writing code, if not more so. I usually like to take a nap afterwards.

Here are a few tips I’ve learned over the years for doing code reviews well.

Review a reasonable amount of code at a time

This is one of the hardest tips for me to follow. When I start a review of a pull request, I am so tempted to finish it in one sitting because I’m impatient and want to get back to my own work. Also, I know that others are waiting on the review and I don’t want to hold them up.

But I try and remind myself that code review is my work! Also, a poorly done review is not much better than no review at all. When you realize that code reviews are important, you understand that it’s worth the extra time to do it well.

So I usually stop when I reach that point of review exhaustion and catch myself skipping over code. I just take a break, move onto something else, and return to it later. What better time to catch up on Archer episodes?!

Focus on the code and not the author

This has more to do with the social aspect of code review than defect finding. I try to do my best to focus my comments on the code and not the ability or the mental state of the author. For example, instead of asking “What the hell were you thinking when you wrote this?!” I’ll say, “I’m unclear about what this section of code does. Would you explain it?”.

See? Instead of attacking the author, I’m focusing on the code and my understanding of it.

Of course, it’s possible to follow this advice and still be insulting, “This code makes me want to gouge my eyes out in between my fits of vomiting.” While this sentence focuses on the code and how it makes me feel, it’s still implicitly insulting to the author. Try to avoid that.

Keep a code review checklist

A code review checklist is a really great tool for conducting an effective code review. The checklist should be a gentle reminder of common issues in code you want to review. It shouldn’t represent the only things you review, but a minimal set. You should always be engaging your brain during a review looking for things that might not be on your checklist.

I’ll be honest, as I started writing this post, I only had a mental checklist I ran through. In an effort to avoid being a hypocrite and leveling up my code review, I created a checklist gist.

My checklist includes things like:

  1. Ensure there are unit tests and review those first looking for test gaps. Unit tests are a fantastic way to grasp how code is meant to be used by others and to learn what the expected behavior is.
  2. Review arguments to methods. Make sure arguments to methods make sense and are validated. Consider what happens with boundary conditions.
  3. Look for null reference exceptions. Null references are a bitch and it’s worth looking out for them specifically.
  4. Make sure naming, formatting, etc. follow our conventions and are consistent.I like a codebase that’s fairly consistent so you know what to expect.
  5. Disposable things are disposed. Look for usages of resources that should be disposed but are not.
  6. Security.There is a whole threat and mitigation review process that falls under this bucket. I won’t go into that in this post. But do ask yourself how the code can be exploited.

I also have separate checklists for different platform specific items. For example, if I’m reviewing a WPF application, I’m looking out for cases where we might update the UI on a non-UI thread. Things like that.

Step Through The Code

You’ll note that I don’t mention making sure the code compiles and that the tests pass. I already know this through the magic of the commit status API which is displayed on our pull requests.

-396

However, for more involved or more risky code changes, I do think it’s worthwhile to actually try the code and step through it in the debugger. Here, GitHub has your back with a relatively new feature that makes it easy to get the code for a specific pull request down to your machine.

If you have GitHub for Windows or GitHub for Mac installed and you scroll down to the bottom of any pull request, you’ll see a curious new button.

clone-pr-in-desktop

Click on that button and we’ll clone the pull request code to your local machine so you can quickly and easily try it out.

Note that in Git parlance, this is not the original pull request branch, but reference (usually named something like pr/42 where 42 is the pull request number) so you should treat it as a read-only branch. But you can always create a branch from that reference and push it to GitHub if you need to.

I often like to do this and run Resharper analysis on the code to highlight things like places where I might want to convert code to use a LINQ expression and things like that.

Sign Off On It

After a few rounds of review, when the code looks good, make sure you let the author know! Praise where praise is due is an important part of code reviews.

At GitHub, when a team is satisfied with a pull request, we tend to comment it and include the ship it squirrel emoji (:shipit:) . That indicates the review is complete, everything looks good, and you are free to ship the changes and merge it to master.

Every team is different, but on the GitHub for Windows team we tend to let the author merge the code into master after someone else signs off on the pull request.

This works well when dealing with pull requests from people who also have commit access. On my open source projects, I tend to post a thumbs up reaction gif to show my immense appreciation for their contribution. I then merge it for them.

Here’s one of my favorites for a very good contributions.

Bruce Lee gives a thumbs up

Be Good To Each Other

Many of my favorite discussions happen around code. There’s something about having working code to focus a discuss in a way that hypothetical discussions do not.

Of course, even this can break down on occasion. But for the most part, if you go into a code review with the idea of both being taught as well as teaching, good things result.

community, personal 0 comments suggest edit

I love a good argument. No really! Even ones online.

The problem is, so few of them are any good. They tend to go nowhere and offer nothing of value. They just consist of one side attempting to browbeat the other into rhetorical submission.

What?! You are not persuaded by my unassailable argument? THEN LET ME MAKE THE SAME POINTWITH ALL CAPS!

ARE YOU NOT CONVINCED?!

red-cardYou want to argue? Argue with this card! Image: from wikipedia CC BY-SA 3.0.

So what makes an argument good? (besides when you agree with me which is always a good move)

A while back, I read an interesting article about Professor Daniel H. Cohen, a philosopher who specializes in argumentation theory, that tackles this question.

As an aside, I wonder how his kids feel arguing with someone who’s basically a professor of arguing? Must be hard winning that argument about extending that curfew.

The article starts off with a scenario that captures 99.9% of arguments (online or offline) well:

You are having a heated debate with friends about, say, equality of the sexes. You’ve taken a standpoint and you’re sticking with it. Before you know it, you’ve got so worked up that, regardless of whether you believe your argument is the most valid, you simply just want to win, employing tactics and subterfuge to seek victory.

I like to think of myself as a very logical reasonable person. But when I read this scenario, I realized how often I’ve fallen prey to that even in what should be dispassionate technical arguments!

I’m pretty sure I’m not the only one. I’m just willing to admit it.

Cohen points out that the “war metaphor” is at fault for this tendency. Often, it’s the so-called “losers” of an argument who really win:

He explains, “Suppose you and I have an argument. You believe a proposition, P, and I don’t. I’ve objected, I’ve questioned, I’ve raised all sorts of counter-considerations, and in every case you’ve responded to my satisfaction. At the end of the day, I say, ‘You know what? I guess you’re right.’ So I have a new belief. And it’s not just any belief, but it’s a well-articulated, examined and battle-tested belief. Cohen continues, “So who won that argument? Well, the war metaphor seems to force us into saying you won, even though I’m the only one who made any cognitive gain.

The point of a good argument isn’t for one person to simply win over the other. It’s ideally for both to come away with cognitive gains.

Even if the goal of an argument is to reach a decision, the goal isn’t to win, the goal is to define the parameters for a good decision and then make the best possible decision with that in mind.

I’ve come to believe that when two reasonably smart people disagree on a subject, at the core, it is often because one of the following:

  1. One or both of the participants is missing key information.
  2. One or both of the participants made a logic error that leads to a wrong conclusion.
  3. The participants agree on the facts, but have different values and priorities leading them to either disagree on what conclusion should come from the facts.

In my mind, a good debate tries to expose missing facts and illogical conclusions so that two in the debate can get to the real crux of the matter, how their biases, experiences, and values shape their beliefs.

I’m assuming here that both participants are invested in the debate. When one isn’t, it becomes overwhelmingly tempting to resort to any means necessary in order to wipe that smug smirk off your opponent’s face.

Troll_Face

Of course, both sides will believe they’re the one who is drawing conclusions from years of objective rational analysis, but they’re both wrong. In the end, we all succumb to various biases and our values. And a good debate can expose those and allow participants to discuss whether those are the right biases and values to have in the first place? That’s where an argument really gets somewhere.

Another philosopher, Daniel Dennett, lays out these rhetorical habits when critiquing or arguing in his book, Intuition Pumps And Other Tools for Thinking:

How to compose a successful critical commentary:

​1. Attempt to re-express your target’s position so clearly, vividly and fairly that your target says: “Thanks, I wish I’d thought of putting it that way.”

​2. List any points of agreement (especially if they are not matters of general or widespread agreement).

​3. Mention anything you have learned from your target.

​4. Only then are you permitted to say so much as a word of rebuttal or criticism.

These habits nicely complement the improved metaphor for arguing espoused by Cohen.

So the next time you get into an argument, think about your goals. Are you just trying to win or are you trying to reach mutual understanding? Then try to apply Dennett’s rhetorical habits as you argue. I’ll try to do the same so if we end up in an argument, there’s a better chance it’ll result in a good one.

This will serve you well not only in your work, but in your personal relationships as well.

code, open source 0 comments suggest edit

Just shipped a new release of RestSharp to NuGet. For those who don’t know, RestSharp is a simple REST and HTTP API Client for .NET.

This release is primarily a bug fix release with a whole lotta bug fixes. It should be fully compatible with the previous version. If it’s not, I’m sorry.

Some highlights:

  • Added Task<T> Overloads for async requests
  • Serialization bug fixes
  • ClientCertificate bug fix for Mono
  • And many more bug fixes…

Full release notes are up on GitHub. If you’re interested in the nitty gritty, you can see every commit that made it into this release using the GitHub compare view.

I want to send a big thanks to everyone who contributed to this release. You should feel proud of your contribution!

Who are you and what did you do to Sheehan?!

Don’t worry! John Sheehan is safe and sound in an undisclosed location. Ha! I kid. I’m beating him senseless every day.

Seriously though, if you use RestSharp, you should buy John Sheehan a beer. Though get in line as Paul Betts owes him at least five beers.

-359John started RestSharp four years ago and has shepherded it well for a very long time. But a while back he decided to focus more on other technologies. Even so, he held on for a long time tending to his baby even amidst a lot of frustrations, until he finally stopped contributing and left it to the community to handle.

And the community did. Various other folks started taking stewardship of the project and it continued along. This is the beauty of open source.

We at GitHub use RestSharp for the GitHub for Windows application. A little while back, I noticed people stopped reviewing and accepting my pull requests. Turns out the project was temporarily abandoned. So Sheehan gave me commit access and I took the helm getting our bug fixes in as well as reviewing and accepting the many dormant pull requests. That’s why I’m here.

Why RestSharp when there’s HttpClient?

Very good question! System.Net.HttpClient is only available for .NET 4.5. There’s the Portable Class Library (PCL) version, but that is encumbered by silly platform restrictions. I’ve written before that this is harms .NET. I am hopeful they will eventually change it.

RestSharp is unencumbered by platform restrictions - another beautiful thing about open source.

So until Microsoft fixes the licensing on HttpClient, RestSharp is one of the only options for a portable, multi-platform, unencumbered, fully open source HTTP client you can use in all of your applications today. Want to build the next great iOS app using Xamarin tools? Feel free to use RestSharp. Find a bug in using it on Mono? Send a pull request.

The Future of RestSharp

I’m not going to lie. I’m just providing a temporary foster home for RestSharp. When the HttpClient licensing is fixed, I may switch to that and stop shepherding RestSharp. I fully expect others will come along and take it to the next level. Of course it really depends on the feature set it supplies and whether they open source it.

As they say, open source is about scratching an itch. Right now, I’m scratching the “we need fixes in RestSharp” itch. When I no longer have that itch, I’ll hand it off to the next person who has the itch.

But while I’m here, I’m going to fix things up and make them better.

code, open source, github 0 comments suggest edit

The first GitHub Data Challenge launched in 2012 and asked the following compelling question: what would you do with all this data about our coding habits?

The GitHub public timeline is now easy to query and analyze. With hundreds of thousands of events in the timeline every day, there are countless stories to tell.

Excited to play around with all this data? We’d love to see what you come up with.

It was so successful, we did it again this past April. One of those projects really caught my eye, a site that analysise Popular Coding Conventions on GitHub. It ended up winning second place.

It analyzes GitHub and provides interesting graphs on which coding conventions are more popular among GitHub users based on analyzing the code. This lets you fight your ever present software religious wars with some data.

For example, here’s how the Tabs vs Spaces debate lands among Java developers on GitHub.

java-tabs-vs-spaces

With that, I’m sure nobody ever will argue tabs over spaces again right? RIGHT?!

What about C#?!

UPDATE: JeongHyoon Byun added C# support! Woohoo!

Sadly, there is no support for C# yet. I logged an issue in the repository about that a while back and was asked to provide examples of C# conventions.

I finally got around to it today. I simply converted the Java examples to C# and added one or two that I’ve debated with my co-workers.

However, to get this done faster, perhaps one of you would be willing to add a simple CSharp convention parser to this project. Here’s a list of the current parsers that can be used as the basis for a new one.

Please please please somebody step up and write that parser. That way I can show my co-worker Paul Betts the error of his naming ways.

humor, personal, company culture 0 comments suggest edit

I avoid mailing lists the same way I avoid fun activities like meetings and pouring lemon juice into bloody scrapes. Even so, I still somehow end up subscribed to one or two. Even worse, once in a while, despite my better judgment, I send an email to such a list and am quickly punished for my transgression with an onslaught of out of office auto replies. You know the type:

Hey there friend! Thanks for your email! No seriously, I’m thanking you even though I haven’t read it. I’m sure it’s important because I’m important.

Unfortunately (for you), I’m off to some island paradise drinking one too many Mai Tais and probably making an ass of myself.

If you need to reach me, you can’t, LOL! You can contact this list of people you don’t know in my absence. Good luck with that!

punishment Wait till you see the punishment for sending an email during the holidays! Photo by: Tomas Alexsiejunas license: CC BY 2.0

If you have such a rule set up, let me humbly offer you a friendly constructive tip:

NOBODY FUCKING CARES!

The universe has gone on for around 14 billion years before you were born just fine. And chances are, it’ll continue to survive after your death for another 100 googol years until the entropy death of the last proton, or another universe inflates to take its place. Whichever comes first.

So in the grand scheme of things, nobody cares that you’re out of the office, on vacation, or worse, too busy to respond to email so you automatically send me one as if I have all the time in the world to deal with more email.

Ok, that might have come across as a eensy weensy bit ranty. I’ll try to tone it down and offer something more constructive. After all, I’ve probably been guilty of this in my past and I apologize and have paid my penance (see photo above).

Maybe there’s a tiny bit of a purpose

The first time I experienced widespread use of out-of-office replies is during my time at Microsoft. And to be fair, it does serve a small purpose. While 99.999999% of the world doesn’t care if you’re out of the office (that’s science folks), sometimes someone has a legitimate need to know who they should contact instead of you. For example, at Microsoft, I had an internal reply set up that directed emails to my manager. The lucky guy.

Fortunately for those using Outlook with Exchange, you can choose a different reply for internal emails than external emails. So definitely go and do that.

The two email rule of out-of-office replies

But what about the rest of us who really don’t care? I offer the following simple idea:

If you must have an out-of-office auto reply, create a rule to only send it when you receive two direct emails without a response. The idea here is that if I send you one email directly, I can probably wait for you to get back to respond. If I can’t, I’ll send you another “hey, bump!” email and then receive auto notice. After all, if I send you two emails, sending me one is fair game.

Also, make sure you never ever ever send an auto-reply when you are not in the TO list. That rule alone will cut out billions of email list out-of-office spam. Ideally, the auto-reply should only occur if you’re the only one in the TO list. Chances are someone else in the TO list will know you’re gone and can reply to the others if necessary. Again, the two email rule could come into play here.

In the meanwhile, I think I’m going to switch tactics. Spam me, I spam you. So I may respond to those auto-replies with something like:

Dear So-and-so,

Hey dude, thanks for letting me know that you’re not in your office. I bet you’re on a really important business trip and/or vacation! I bet you have such important things to do there!

Me? Not so much. I wish I was on an important business trip and/or vacation.

It turns out, I have nothing better to do than respond to your automatically generated email to me! Thank you so much for that. The fact that it had your name at the bottom of the email and my email address in the TO: list was a nice personal touch. It really felt like you took the time to lovingly craft that email just for me.

So I thought it would be rude not to respond in kind with a thoughtful response of my own.

Sincerely and without regret,

Phil

p.s. I left you a little surprise in your office, but since you’re not there, I hope it doesn’t die before you get back. If it smells bad when you get back, you’ll know.

Hopefully email clients take this up and just implement it automatically because I don’t expect people to take the time to do this right.

What do you think? Are auto-replies more important than I give credit or do we live in a world with a lot of narcissists who must be stopped? Tell me how I’m right or wrong in the comments. Thanks!

code, community 0 comments suggest edit

There’s something about being outdoors in Alaska that inspires poetic thoughts. In my case it’s all bad poetry so I’ll spare you the nausea and just show a photo instead.

This was taken descending from Flattop, a strenuous but easy climb. At the top, we couldn’t see more than ten yards because of the clouds. But as we descended, they suddenly cleared giving us a sliver of a view of the ocean and coastline.

flattop-hike

My first experience of Alaska was when my family moved out here from the tropical island of Guam. Yeah, it was a bit of a change. I went to high school there and returned to Anchorage every Christmas and Summer break during college.

When I lived there, I was completely oblivious to the existence of a software community out here. But around four years ago, I brought my family out to visit my parents and on a whim gave a talk to the local .NET user group.

This has become kind of a thing for me to try and find a local user group to speak at when I go on vacation.

This summer, after subjecting my wife to back to back weeks of travel, I decided to give her a long overdue break from family duties and take my kids to Alaska. One benefit of working at a mostly distributed company is I can pretty much work from any location that has good internet.

My parents were game to watch and entertain the kids while I worked from their house. Since I was up there, I also got in touch with folks about giving another talk.

Unfortunately, the .NET user group had disbanded not long after I left. They assured me it wasn’t my fault. It turns out that it is very difficult to get good speakers up there.

This isn’t too surprising. Alaska is pretty out-of-the way for most people. At the same time, it’s an amazing place to visit during the months of June and July. The days are long and sunny. There’s all sorts of outdoor activities to partake in.

So if you’re a decent speaker passionate about technology and happen to find yourself up there for vacation or otherwise, let me know and I can put you in touch with some people who would love to have you give a talk. You can probably even write-off a portion of your vacation if the talk is related to your work (though you should talk to your tax person about that and don’t listen to me).

alaska-github-talk

They put together an ad-hoc event while I was there and we had around twenty-five or so people show up. It doesn’t sound like a lot, but it’s a pretty good number for Anchorage and they really appreciate it. Afterwards, I recommend going out for some Alaskan Amber. It’s quite a good beer! And definitely hike Flattop.

open source 0 comments suggest edit

A while back I wrote a riveting 3-part developer’s guide to copyright law and open source licensing for developers.

I’m pretty sure you read every word at the edge of your seat. Who doesn’t love reading about laws, licenses, and copyright!?

Seriously though, I hope some of you found it useful. In this post, I want to talk about some recent developments that should make it easier for developers to license their code.

Choosealicense.com

A couple days ago I published a blog post on the GitHub blog about an effort I’ve been involved with, http://choosealicense.com/. Per the about page:

GitHub wants to help developers choose a license for their source code.

If you already know what you’re doing and have a license you prefer to use, that’s great! We’re not here to change your mind. But if you are bewildered by the large number of OSS license choices, maybe we can help.

I’m interested in helping developers be explicit and clear about their intent for their code. Adding a LICENSE (or an UNLICENSE if that’s your thing) file to the root of your public repository is a good way to state your intent. We even include an option if you really do want to retain all rights to your code, you grinch (I kid! I do not judge.)

But before you can choose a license, you need to be informed about what the license entails. That’s what we hope the site helps with.

Combined with the site, GitHub now has a feature that lets you choose a license when creating a repository on GitHub.

AddALicense.com

That’s great! But what about all your existing projects? Well one of my co-workers, Garen Torikian, has you covered. He built http://addalicense.com/ as a little side project. Note that the project is full of disclaimers:

This site is **not owned by or affiliated with GitHub**. But I work there, and I’m using the API to add each new license file. You’ll be asked to authenticate this app for your public repositories on the next page.

Perhaps in the future, we may integrate this into http://choosealicense.com/.

But in the meanwhile check it out and get those projects licensed!

company culture 0 comments suggest edit

A finely honed bullshit detector is a benefit to everyone. Let’s try a hypothetical conversation to test yours!

“Hey, we should release that under a more permissive license for XYZ reasons.”

“We’d like to, but the lawyers won’t let us.”

If it’s not malfunctioning, you should feel your bullshit detector tingling right now.

bull Yep, it’s a bull. Photo by Graeme Law CC BY 2.0

A lot of folks think that a lawyer’s job is to protect the business at all costs – that their job is to say “no!” Unfortunately, many places do structure it that way. After all, if a lawyer says “go ahead” and you get sued, the lawyer loses. But if the lawyer says “don’t”, there’s no immediate downside for the lawyer. Eventually the business may collapse from inaction, but there’s always teaching at law school as a backup. So why would the lawyer ever say “yes” in such a situation?

One of the best lessons I learned while at Microsoft was from Scott Guthrie when I expressed concern that the legal team wouldn’t let us break new ground with how we shipped open source.

He reminded me that the lawyers work for us. We do not work for the lawyers. If the lawyers had their way, we wouldn’t do anything because that’s the safest option.

You can see why so many people love the red polo.

Many decisions where legal gets involved are business decisions, not legal decisions. Unless the decision is downright illegal, the lawyer’s job is to help figure out how to do what’s best for the business. Along the way, they should make sure we’re aware of the risks, but also find ways to minimize the risks. At least that’s what a good lawyer does and I’ve been fortunate to work with some.

At the end of the day, even if the lawyer is uneasy about a course of action, they do not get to make the business decisions. That’s someone else’s job (unless you happen to work at a law firm I guess). Perhaps it’s your job.

So when someone tells you that “legal won’t let us do XYZ”, unless they follow that with “because it’s illegal and will land us all in jail and that’s no fun”, you should recognize it as a copout.

Sometimes what they mean is “I don’t really know what’s in the best interest of our business (or I’m too busy to care) so I’ll play it safe and blame the lawyers.”

What you hope they mean is “we won’t do this because it is not in the best interest of our business.” Now that is a fair answer. You may disagree, but it serves as a starting point for a more interesting conversation.

blogging, open source 0 comments suggest edit

Google is shuttering Google Reader in a little over a day (on July 1st, 2013) as I write this. If you use Google Reader to read my blog, this means you might miss out on my posts and I KNOW YOU DON’T WANT THIS!

Then again, maybe this is finally your chance to make a break, get some fresh air, stop reading blogs and start creating! I won’t hold it against you.

But for the rest of you, it’s a good time to find a replacement. Or at the very least follow me on Twitter since I do tweet when I blog.

There’s a lot of Google Reader replacements out there, but only two that I like so far.

Feedly

feedly

Feedly is gorgeous. There are apps for many platforms, but the browser works pretty well. Also, you can use Google to log into it and import your Google Reader feeds. I hope Google allows exporting to Feedly and other aggregators after July 1st even as they close down the Google Reader site.

The problem I have with Feedly is that it doesn’t work like Google Reader. It wouldn’t be so bad if it had a better flow for reading items, but I find its interface to be quirky and in some cases, unintuitive. For example, it seems I have to mark items as read by clicking “mark above articles as read” rather than having it do it automatically like Reader does after you scroll past it.

This leads me to…

Go Read

go-read

Go Read is a late entry into the list, but there are three important things I really like about it:

  1. It is intended to be a clean and simple clone of Google Reader.
  2. It supports Google Reader’s keyboard shortcuts.
  3. It is open source and up on GitHub!

For some more details, check out the announcement blog post by the author, Matt Jibson, a developer at Stack Exchange:

I would like to announce the release of Go Read. It as a Google Reader clone, and designed to be close to its simplicity and cleanliness. I wanted to build something as close to Google Reader as made sense for one person to build in a few months.

It’s basically Google Reader, but without all the cruft and where you can send pull requests to improve things!

In fact, there’s already a few pull requests with some nice user interface polish that should hopefully make it into the site soon.

Despite some false starts, I have it up and running on my machine. I sent a few pull requests to update the README to help other clueless folks like me get it set up for hacking on.

So check it out, import your Google Reader feeds, and never miss out on another Haacked.com post EVER!

UPDATE: I forgot to mention what is perhaps the most important reason for me to prefer Go Read. I don’t want to end up in another Google Reader situation again and rely on an RSS Aggregator that isn’t a solid business and might not stick around. At least with an open source option, I have the code running on my own machine as a backup in a pinch.

code 0 comments suggest edit

UPDATE: The .NET team removed the platform limitations.

Let me start by giving some kudos to the Microsoft BCL (Base Class Library) team. They’ve been doing a great job of shipping useful libraries lately. Here’s a small sampling on Nuget:

However, one trend I’ve noticed is that the released versions of most of these packages have a platform limitation in the EULA (the pre-release versions have an “eval-only” license which do not limit platform, but do limit deployment for production use). At this point I should remind everyone I’m not a lawyer and this is not legal advice blah blah blah.

Here’s an excerpt from section 2. c. in the released HttpClient license, emphasis mine:

a. Distribution Restrictions. You may not

  • alter any copyright, trademark or patent notice in the Distributable Code;
  • use Microsoft’s trademarks in your programs’ names or in a way that suggests your programs come from or are endorsed by Microsoft;
  • distribute Distributable Code to run on a platform other than the Windows platform;

I think this last bullet point is problematic and should be removed.

Why should they?

I recently wrote the following tweet in response to this trend:

Dear Microsoft BCL team. Please remove the platform limitation on your very cool libraries. Love, cross-platform .NET devs.

And a Richard Burte tweeted back:

And that pays the rent how exactly?

Great question!

There is this sentiment among many that the only reason to make .NET libraries cross platform or open source is just to appease us long haired open source hippies.

Well first, let me make it crystal clear that I plan to get a haircut very soon. Second, the focus of this particular discussion is the platform limitation on the compiled binaries. I’ll get to the extra hippie open source part later.

There are several reasons why removing the platform limitation benefits Microsoft and the .NET team.

It benefits Microsoft’s enterprise customers

Let’s start with Microsoft’s bread and butter, the enterprise. There’s a growing trend of enterprises that support employees who bring their own devices (BYOD) to work. As Wikipedia points out:

BYOD is making significant inroads in the business world, with about 75% of employees in high growth markets such as Brazil and Russia and 44% in developed markets already using their own technology at work.

Heck, at the time I was an employee, even Microsoft supported employees with iPhones connecting to Exchange to get email. I assume they still do, Ballmer pretending to break an iPhone notwithstanding.

Microsoft’s own software supports cross-platform usage. Keeping platform limitations on their .NET code hamstrings enterprise developers who want to either target the enterprise market or want to make internal tools for their companies that work on all devices.

It’s a long play benefit to Windows 8 Phone and Tablet

While developing Windows 8, Microsoft put a ton of energy and focus into a new HTML and JavaScript based development model for Windows 8 applications, at the cost of focus on .NET and C# in that time period.

The end result? From several sources I’ve heard that something like 85% of apps in the Windows app store are C# apps.

Now, I don’t think we’re going to see a bunch of iOS developers suddenly pick up C# in droves and start porting their apps to work on Windows. But there is the next generation to think of. If Windows 8 devices can get enough share to make it worthwhile, it may be easier to convince this next generation of developers to consider C# for their iOS development and port to Windows cheaply. Already, with Xamarin tools, using C# to target iOS is a worlds better environment than Objective-C. I believe iOS developers today tolerate Objective-C because it’s been so successful for them and it was the only game in town. As Xamarin tools get more notice, I don’t think the next generation will tolerate the clumsiness of the Objective-C tools.

There’s no good reason not to

Ok, this isn’t strictly speaking a benefit. But it speaks to a benefit.

The benefit here is that when Microsoft restricts developers without good reason, it makes them unhappy.

If you recall, Ballmer is the one who once went on stage to affirm Microsoft’s focus on developers! developers! developers! through interpretive dance.

ballmer-developers-dance

Unless there’s something I’m missing (and feel free to enlighten me!), there’s no good reason to keep the platform restriction on most of these libraries. In such cases, focus on the developers!

At a recent Outercurve conference, Scott Guthrie, a corporate VP at Microsoft in change of the Azure Development platform told the audience that his team’s rule of thumb with new frameworks is to default it to open source unless they have a good reason not to.

The Azure team recognizes that a strategy that requires total Windows hegemony will only lead to tears. Microsoft can succeed without having Windows on every machine. Hence Azure supports Linux, and PHP, and other non-Microsoft technologies.

I think the entire .NET team should look to what the Azure team is doing in deciding what their strategy regarding licensing should be moving forward. It makes more developers happy and costs very little to remove that one bullet point from the EULA. I know, I’ve been a part of a team that did it. We worked to destroy that bullet with fire (among others) in every ASP.NET MVC EULA.

Update: It looks like I may have overstated this. Licenses for products are based on templates. Typically a product team’s lawyer will grab a template and then modify it. So with ASP.NET MVC 1 and 2, we removed the platform restriction in the EULA. But it looks like the legal team switched to a different license template in ASP.NET MVC 3 and we forgot to remove the restriction. That was never the intention. Shame on past Phil. Present Phil is disappointed.

At least in this case, the actual source code is licensed under the Apache 2.0 license developers have the option to compile and redistribute, making this a big inconvenience but not a showstopper.

Next Steps

I recently commented on a BCL blog post suggesting that the team remove the platform limitation on a library. Immo Landwerth, a BCL Program Manager responded with a good clarifying question:

Thanks for sharing your concerns and the candid feedback. You post raised two very different items:

​(1) Windows only restriction on the license of the binaries

​(2) Open sourcing immutable collections

From what I read, it sounds you are more interested in (1), is this correct?

The post he refers to is actually one that Miguel de Icaza wrote when MEF came out with a license that had a platform restriction entitled Avoid the Managed Extensibility Framework. Fortunately, that was quickly corrected in that case.

But now we seem to be in a similar situation again.

Here was my response:

@Immo, well I’m interested in both. But I also understand how Microsoft works enough to know that (1) is much easier than (2). :P

So ultimately, I think both would be great, but for now, (1) is a good first step and a minimal requirement for us to use it in ReactiveUI etc.

So while I’d love to see these libraries be open source, I think a minimal next step would be to remove the platform limitation on the compiled library and all future libraries.

And not just to make us long haired (but soon to have a haircut) open source hippies happy, but to make us enterprise developers happy. To make us cross-platform mobile developers happy.