What I Learnt from Releasing an Open Source Tool

A few weeks ago The Scale Factory released s3audit, a command line tool for auditing the settings of AWS S3 buckets.

Photo by Joshua Aragon on Unsplash

Since its release s3audit has garnered a modest amount of interest from the wider AWS community. Following the release:

These figures are modest compared with the many popular open source projects which are available. But it’s fair to say my expectations of interest were much lower when we decided to make the tool public. And it’s certainly the first time something I’ve released publicly has achieved even modest interest on this level.

Here I’d like to talk a little bit about what I learnt from releasing s3audit; because it’s actually a perfect case study for the importance of lean principles and MVPs when building software and of overcoming the natural fear which often comes from releasing software.

A bit of background

I initially built s3audit because I wanted to get an overview of the settings for S3 buckets in an AWS account. So, wanting to be a responsible DevOps person, I thought I should automate this as much as possible.

I did a quick search for an existing tool and couldn’t find anything which entirely suited my needs. So I decided to quickly put something together.

Building s3audit

The majority of the coding was done over about 2 working days. I decided to write it in Node.js because I’m familiar with JavaScript, and TypeScript, so I was confident I could get something working quickly. I wanted to be able to get on with the task in hand without being blocked by putting this together.

On the other hand, I’ve never written a CLI tool with Node.js before so there was an opportunity to learn something new as well. Importantly though, the learning curve wouldn’t take up too much time.

I also considered using Go because I’d like to learn that a bit more, and in some ways if feels like a more sensible option for a CLI tool. But the learning curve would have been too steep and I needed to avoid getting distracted from the actual task in hand.

So Node.js it is. I used the excellent [oclif](https://github.com/oclif/oclif) which makes writing a CLI tool for Node.js super simple. To display the output I found Listr, a library for creating task lists in the terminal. I wasn’t building a task list but it gave me the ability to create lists with ticks and crosses which is what I needed.

Making it public

As this point we realised that this was something other people might find useful and decided to make it public. A tweet was put out announcing its release which some people actually interacted with.

At this point I started to panic. I’d expected this to go the same way as every other thing I’d made public, that is to disappear into GitHub oblivion. The problem with being a developer most of the time is that your mum doesn’t know what GitHub is, so you don’t even have her to cheer you on.

When I first hacked the tool together in a just over a day I wasn’t sure if it would be useful for anyone else, releasing it has been the last thing on my mind.

It didn’t have any tests because it hadn’t needed them. It was a simple tool to quickly get information from the AWS API that I wasn’t expecting to use again. It would be tested by verifying the information before acting on it. The code in general wasn’t exactly a work of art either, I certainly wasn’t going to be printing it out to put on the fridge door.

I also had serious doubts about its usability, because of my decision to use Listr. Listr is supposed to update the content in the terminal but I was finding that instead I was getting duplicated output, so incomplete information for buckets was outputted and then later on the complete information was displayed. I spent quite a few hours trying to fix the issue, I’m still not clear if it’s an issue with Listr itself or my use of it. In the end I decided that it wasn’t worth my time fixing the issue, and got around it by grouping the output together so I could see where the complete output started. You can view that change in the git history:

Code change to group command output

This worked well enough for me, but I was pretty worried that it would result in other people dismissing the tool as unusable. In the end that didn’t happen.

I had other concerns as well because of the limitations of using a task list library for something which wasn’t a task list — not everything I was adding would necessarily need a tick or a cross and I sometimes wanted to display a bit more context, for example which SSE algorithm was being used. I decided to ignore these problems for now.

Subsequently, I realised that I needed the output in a more usable format anyway. So I added a flag for outputting as CSV so that I could open it up in a spreadsheet and add conditional formatting to give me lots of lovely green and red boxes. I could also now include the extra information in the CSV output, a win-win. If it gets developed more in the future then the console output will probably be changed for something more appropriate.

What I learnt

  • DevOps and TypeScript go great together!
  • You shouldn’t assume that just because something doesn’t exist already that there’s no demand for it. Everyone else who needs it is probably just too busy to build it. Or maybe you just haven’t Googled hard enough and your work isn’t needed at all, at least you still get to write a Medium post about it.
  • Don’t spend too much time worrying about the quality of your code, or whether it’s ‘good enough’. Until you get something out there you’ll never know what good enough is. All that really matters is whether your software has business value.
  • Keep it simple. It’s much easier to move fast and change things later if the code is kept as simple as possible. On the other hand, if it’s over-engineered with complicated abstractions it’ll be much harder to change things.
  • Use existing libraries where possible. Even if they don’t do exactly what you need they’ll get you to an MVP quickly. You’re then in a better position to decide whether the library still works based on a better idea of the direction you need to move in.
  • Don’t be afraid to put something out there. Being nervous when making your work public is normal, whether that’s code or a Medium post. But people are nice, and they’ll happily help you improve things through PRs or helpful feedback. Most of the time no one will notice you, but just maybe you’ll actually create something that someone else finds useful. And for a developer that’s about as good as it gets.

I’m a consultant at The Scale Factory, where we empower technology teams to deliver more on the AWS cloud, through consultancy, engineering, support, and training. We might be able to help you too.