Octokit and the Documentation Nightmare

Before I get into the meat of this series of posts, I would like to set the scene. Like many organisations that perform some level of software development these days, we use GitHub. Here at CareEvolution, some developers use the web interface extensively, some use the command line, and others use the GitHub desktop client1, but most use a combination of two or more, depending on the task. This works great for developers, who have each found a comfortable workflow for getting things done, but it is not so great for those involved with DevOps, QA, or documentation where there is a need to find out user-friendly details of what the developers did. Quite often, a feature or bug fix involves several commits and while each has a comment or two, and perhaps an associated pull request (PR) or issue has a general description, but there is no definitive list of "this is what release X contains" that can be presented to a customer. Not only that but sometimes a PR or issue is resolved in an earlier release and merged forward. While we have lists of what a release is going to include, quite often there is more detail that we would like to include, and we often have additional changes as we adapt to the changing requirements of our customers. All this means that one or more people end up trawling the commits, trying to determine what the changes are. It is not a happy task.

"There is nothing more difficult to take in hand, more perilous to conduct, or more uncertain in its success, than to take the lead in the introduction of a new order of things."

Niccolo Machiavelli
The Prince (1532)

Now, I know that this could all be avoided if people documented changes more clearly, perhaps added release notes to commits, raised issues for documentation changes, or created release notes on the release when it is made. However, no matter how noble change may be, anyone who has worked in process definition for any length of time will know that changing the behaviour of people is the hardest task of all, and therefore it should be avoided unless absolutely necessary. It was with that in mind that I decided mining the existing data for information would be an easier first step than jumping straight to asking people to change. So, with the aim of making life a little easier, I started looking at ways to automate the trawling.

I figured that by throwing out noisy and typical developer non-descriptive commits like "fixed spelling" or "updated comment", and by combining commits under the corresponding PR or issue, I could create useful summary of changes. This would not be customer-ready, but it would be ready for someone to turn into a release note without needing to trawl git history. In fact, if I included details of who committed the changes, it might even provide a feedback loop that would improve the quality of developer commit messages; developers do not like interruptions, so anyone asking for more detail on a commit they made should start to reinforce that if they wrote better commits, PRs, issues, they would get less interruptions.


Octokit .NET logoAfter a dismissing using git locally to perform this task (I figured those who might need this tool would probably not want to get the repository locally) and reading up on the GitHub API a little, I cracked open LINQPad —my tool of choice for hacking— and went looking for a Nuget package to help. It was during that search that I happily stumbled on Octokit, the official GitHub library for interacting with the GitHub API. At the time of writing, Octokit reflects the polyglot nature of GitHub users, providing variants for Ruby, .NET, and Objective C, as well as experimental versions for Python, and Go. I installed the Octokit Nuget package into LINQPad and started hacking (there is also a reactive version for IObservable fans).

Poking around the various objects, and reading some documentation on GitHub (Octokit is open source), I got a feel for how the library wrapped the APIs. Though, I had not yet got any code running, I was making progress. Confident that this would enable me to create the tool I wanted to create, I started writing some code to gather a list of releases for a specific repository and stumbled over my first hurdle; authentication. It turns out it is not quite as straight-forward as I thought (the days of username and password are quite rightly behind us3), and so, my adventure began.

And then…

This is a good place to stop for this week, I think. As the series progresses, I will be piecing together the various parts of my "release note guidance" tool and hopefully, end up with a .NET library to augment Octokit with some useful history mining functionality. Next time, we will take a look at authentication with Octokit (and there will be code).

  1. OSX and Windows variants 

  2. or, James Bond for kids 

  3. OK, that's a lie, but I want to encourage good behaviour 

Kalamazoo X 2014

Last year, I experienced the Kalamazoo X Conference for the very first time. It was an extremely emotional experience and one of two events that catalysed some ongoing personal change (the other was changing jobs after 12 years).

This year, I returned to Kalamazoo X, curious as to what the experience would hold. It was daunting; it felt different.

It wasn't worse different or better different. It wasn't different because the talks were new or the venue had changed to accommodate more attendees. I initially thought it was different because last year's talks were focused on the self and "accepting who you are", whereas this year's centered around others and how we can benefit those around us.  But then I realised that view is coloured by who I am (or was). It was different because I was different.

My life changed after attending Kalamazoo X last year. After the conference (perhaps even during), I started to reflect on who I was, faced old and painfully familiar demons, and began focusing on my well-being in a way I had not allowed myself to before. I began to recognise that I was broken and as the weight of one of the worst winters in history crushed my spirit, I finally sought professional help.

It was a long time coming. Friends had urged me to try counseling for years and perhaps once or twice, I had conceded they had a point, but that was just to shut them up; I knew I wasn't weak like that, I was strong enough to weather my problems alone, to be a "man", to cope. But coping isn't enough. It isn't enough for me or those around me and coming to that realisation is crushing, at least at first.

I am still working through that personal change, the cliched "journey of self-discovery", and I am all the better for it. Kalamazoo X 2013 started something, something that affected how I experienced Kalamazoo X 2014 and life in general. I am certain Kalamazoo X 2014 has started something too.

For me, Kalamazoo X isn't about learning something new or retweeting a pithy statement (though I certainly enjoyed that part). It is about perception and coming to terms with the things I have to let go. It's about growing and perceiving that growth.

I hope to return to Kalamazoo and the X conference year upon year, not only to measure my own growth, but also to see the growth of others. The software development community is incredibly nurturing and nowhere exemplifies that more than Kalamazoo X.

KalamazooX 2013

I struggle to put into words the Kalamazoo X Conference, more commonly known as KalamazooX, a single day, single track non-tech conference for techies. The difficulty is not in describing the talks, the speakers, the venue or the overall experience, describing the conference in such terms is easy; the talks were insightful and inspirational, the speakers were passionate and informative, the venue was accessible and appropriate, and the overall experience was emotionally demanding and entirely worthwhile. To describe what KalamazooX was to me, specifically, to reach deep inside and expose the raw emotions, to be open and honest about me, that is difficult.

It was the simple mantras:

It's not about you.
– Jim Holmes (@aJimHolmes)

Move the elephant. Direct the rider. Shape the path.
– Todd Kaufman (@toddkaufman)

It was the inspirational stories behind Todd Kaufman's talk on enacting change or Mike Wood's (@mikewo) talk on choices of doing the right thing, saving and changing lives, and becoming a better person.

It was the tears that welled in my eyes during Layla Driscoll's (@layladriscoll) talk on being happy, after she encouraged us to sit with our eyes closed and think about who we are. I wrote, "I am sensitive, funny, creative."

It was the encouragement from Leon Gersing (@rubybuddha) and Alan Stevens (@alanstevens) to take time out from time and reality, to meditate, and to find our inner voice.

It was the relief I felt in hearing Alan Stevens say, "you do not require approval from any external source," or Elizabeth Naramore (@ElizabethN) say, "It's okay for it not to be okay."

It was the moment I wrote in my notebook, "I feel less special than others. Is that true? Am I? Or do I need to redress my self image?" I think we both know the answer to that (though some have known a lot longer than others).

It was connecting with others in unexpected, overwhelming and assuring ways.

I do not believe for an instant that I was the only one in attendance that was deeply moved and I suspect that those who were returning attendees already knew about the impact this event can have. What a secret they have kept, hiding the true value of this event behind such dismissive phrases as "My favourite conference of the year!" and "It's a non-tech conference for techies. It's all about soft skills." Such pedestrian phrases pay no due to the experience at all. A more accurate and yet still inadequate phrase was tweeted to me by Michael Letterle (@mletterle) during this years event:

Now, you may think I'm being overly dramatic or reverent and you might be right. I have a tendency toward such things, but rather than assume that be the case, I encourage you to attend next year's KalamazooX and experience it for yourself (or at least look through the #kalx13 tweets). If, having done so, you still feel I have been exaggerating, I will concede and leave you and your cold, black heart to //Build, PyCon or whatever it is that floats your ghost ship (just playing, I'll still love you really).

To close, I thank Michael Eaton (@mjeaton), his team and all the speakers1 for putting on an event so cathartic that even writing about it overwhelms me a little. To uncover a part of oneself is enlightenment, to see that reflected in others is KalamazooX.

  1. Besides those mentioned above Suzan Bond (@suzanbond), Jen Myers (@antiheroine), Brian H Prince (@brianhprince), Jeff Blankenburg (@jeffblankenburg) and Justin Searls (@searls) all gave amazing talks.