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 

Why software bugs exist and how you can help

Numbers in software development are represented by fixed size variables represented in binary. These are usually 8, 16, 32 or 64 bits (each bit represents a 1 or a 0). When we develop software, we choose which of these will provide enough space for the thing we are representing.

Recently, the Gangnam Style video on YouTube surpassed 2,147,483,647 views and it appeared as though the view counter broke. That number is significant because it is the upper limit of a 32-bit signed integer. It turns out that the video view count was being represented using a 32-bit signed integer — a signed value1 can represent whole numbers in the range -2,147,483,648 through 2,147,483,647; it cannot represent any number outside that range.

Though, according to YouTube, this turned out to be an Easter egg2, the bug was there before they updated the counter to 64-bit and it certainly is not the first time a number has pushed the limits. For example, the use of two digits to represent a year that contributed to the infamous fizzle that was Y2K.

But why? Why are there bugs at all?

Although it may seem like software bugs are there just to ruin your day, they were not intentionally put there or maliciously inserted to give you a reason to "Office Space" your device. As software engineers we have to consider a variety of constraints on the software we are developing. How much space does it need to run? How much space will there be on the device on which it is to run? How fast does it have to be?  How many years will the software be in use3? What other software will be running? And we have deadlines by which our work has to be completed. In fact, software engineers tend to consider a whole host of things such as the requirements of the software (functional, spatial, and temporal4), the specification of the system on which it is to execute, project deadlines and budgets, and the expectations of the end user.

Almost always, there has to be compromise. Even though a solution might be possible that accommodates all considerations, we have to deliver software in a time frame that people will pay for and some things just take too long or cost too much. That is not to say that all software bugs are because of time and money, some exist because of mistakes and as a consequence of poor design.

What does it all mean?

Software engineers like myself do not want you to encounter bugs. We work very hard and the QA teams work very hard to ensure that you do not get buggy software; if we see a problem, we do what we can to address it. To find these bugs, we try to consider all the ways our software might be used and test them. Unfortunately, most bugs do not advertise their existence quite so obviously or politely as YouTube's view counter bug. For example, when in comes to the infinite ways any one device might be configured with different peripherals and apps installed, we just cannot test them all; the system is too complex5.

 Good developers welcome user feedback. We need your help.

Next time you encounter a bug in the software you use, whether it is a mobile app, a website, an ATM, a desktop application, or some other device, spare a thought for the software engineers. Remember, good developers welcome user feedback. Take a moment to tell them or the publishers of the software about the problem.

  • What did you type, touch, or click?
  • What else was running on your device?
  • What part of the software were you in?
  • What Internet browser or operating system were you running?
  • What versions?

Be as detailed as you can. All these details and more can help a software engineer track down, reproduce and ultimately fix that bug.

There is no malice in a software bug. It was not put there specifically to ruin your day. However, without your help, it will not go away. So, reach out to the developers and tell them, they will thank you for it.

Today's featured image is based on Software Bugs by Martin Maciaszek.

  1. signed means it can be positive or negative 

  2. An Easter Egg is a hidden feature often added to software as an amusement for users who find it. Examples include the "barrel roll" in Google or the flight simulator in Excel 

  3. Underestimation of this was a big contributor to Y2K 

  4. i.e. how it works, what space it needs, and how long it takes to run and for how long it has to run 

  5. That's a discussion for another time 

Change Requests

Much like my previous post on Meeting Etiquette, this is a topic I feel strongly about. I am sure there are good reasons that people will hate some of my suggestions and I'd love to hear them, but here are my views on change requests1 based on my personal experiences.

All work is a change

I loathe projects that differentiate new work from changes to existing work. It creates two different process flows for little gain, creating points for confusion and mistakes. If all work items, whether new features, bug fixes or enhancements to existing features are raised as change requests, the work flow is the same. Everything should be tied back to requirements, regardless of the type of work, so arguments that claim there is a difference just don't wash with me. Consider a new feature as a change from not having it to having it, after all, that's exactly what it is.

Whatever the work is that is being conducted must still be implemented, reviewed and tested against requirements. Why make it harder than it needs to be?

Specify requirements, not solutions

There are many times I've been assigned a requirement that tells me how to fix something, not what needs fixing. Let's face it, everyone has an opinion but change requests are not the place to express them (except perhaps as a suggestion in the comments somewhere). A change request should clearly state the requirements that drive the change (i.e. the things that can be used to identify when the change request has been resolved) and any other information that may help (for example, steps to reproduce a bug or some rationale behind the change required).

Be descriptive

If I see one more change request with a summary or title like "Change to menu dropdown" or "Display control update", I will be rather miffed and may hurt someone (I'm British, "miffed" is just above "peeved" on the British Standards Anger Scale2). The title of a change request is very important and should give a clear indication of what the change request actually requires. Think of it a bit like twitter; it's much nicer reading some useful information in a tweet than it is to learn that someone just had a coffee. If the title is not clear, time is wasted in going to look at the description every time someone sees that change request. Every status meeting, every discussion, click click click. Save everyone the effort and get it right first time, and if you spot a title that isn't clear enough, fix it right away.

Add value

Finally, when adding comments, additional description, attachments or anything else to a change request, make sure it adds value. Leave an trail for those who follow in your footsteps so that they can discover what changed and why. Document important discussions and decisions. If you don't, you are destined to go around in circles.

Manage releases by managing change

Target changes at releases and review new changes regularly. This way, new requests raised during that release cycle can be considered for inclusion and deferred changes can be ignored until after the release. Each time a new release is started, review all the open requests and determine if they should be rejected, deferred or included in that release. Justify and document rejections in case a duplicate is raised and make sure to link duplicate issues as they can add value to one another.

Have meaningful states

I feel that there are the following possible states for a change request in any sane process to manage them.

  1. Raised
  2. Assigned
  3. In progress
  4. Ready for review
  5. Passed review
  6. Merged to trunk
  7. Rejected
  8. Closed

These are clear, unambiguous states.

  • If something is marked as "Raised", it hasn't been assigned to any release and no work should be happening on it.
  • If it's "Assigned", it should be targetted at a release (even if it's only intended for investigation at first – it can always be removed from the release back to "Raised" or rejected and closed).
  • If someone is working on something, that something should be marked as "In progress" as this helps to track progress at a glance and can also be useful if resources become available and things need reassigning.
  • If something passes testing, close it, unless you really don't trust the test team, in which case have a "Passed test" state and then review the results before closing3.

Considering these basic states, the workflow looks something like this:

State flow diagram
State flow diagram

You could add additional states if you so desired but I feel that these cover the bases well enough and provide an easy to follow work flow.

Closed means closed

Change request management gets messy when the process allows for closed requests to be re-opened. If a closed request seems like it really is now needed, raise a new request. Don't close change requests just because they aren't being done right away; if it's a real issue, then it should remain open until it is resolved.

Not always, but mostly

The guiding principle for me when it comes to change requests is simplicity. Don't make your process more complicated than it needs to be. Make it easy to follow and hard to get wrong. While I'm yet to encounter a project that required anything different to what I've suggested, I am certain there are exceptions, so if you have any, let me know. This is often a contentious, polarising topic, so I expect someone, somewhere to emphatically insist I am wrong. I can accept that, so I look forward to finding out even better ways to manage change.

  1. I made that up 

  2. You may also know them as issues, bugs, defects or some other moniker that ultimately means "a repository of things to do". 

  3. Flippant remarks aside, this may be valuable if you need to perform a round of customer acceptance testing after internal testing before closing out change requests.