Learn Docker With My Newest Course

Dive into Docker takes you from "What is Docker?" to confidently applying Docker to your own projects. It's packed with best practices and examples. Start Learning Docker →

Maintaining an Open Source Project, from Handling Issues to Releases


A 1 hour live demo that uses various git commands, Travis-CI and GitHub features to fix a bug and push a new release.

Quick Jump: Live Demo of Fixing a Bug in One of My Projects

This video walks through a real use case where someone submit a bug report in one of my most popular open source projects, which is an Ansible role to install Docker and Docker Compose on Debian / Ubuntu.

This 1 hour video walks through:

  • How to get good information from a GitHub issue
  • Debugging Python specific errors and general errors
  • Submitting related bug reports in other people’s repos
  • Running local tests before you commit your code
  • Various git commands to make good git commit messages and fixing commit mistakes
  • Keeping your changelog up to date
  • Using Travis-CI to help test your code (and pull requests) in multiple environments
  • Using tags to create GitHub releases
  • Pushing the new release to the Ansible Galaxy

Most of the patterns used in this video can be applied back to any open source project. It’s what I do for pretty much all of my projects.

This video was a live recording, so it includes unexpected errors and new things to think about when everything didn’t go as planned. The only thing I edited was speeding up points where we waited a few minutes for a command to finish running.

Live Demo of Fixing a Bug in One of My Projects

Timestamped Table of Contents

  • 0:43 – The patterns used in this video can be used in any project
  • 1:46 – Trying to get useful information out of issues that folks open
  • 2:47 – A fun bug with virtualenv 20.0.3 related to symlinks
  • 5:23 – Going back 1 level of abstraction really helps to debug errors
  • 7:07 – Opening issues on related repos that are the cause of your library’s bugs
  • 8:00 – Once you know the problem, the solution is usually pretty straight forward
  • 9:35 – Debian and Ubuntu LTS are great server operating systems due to stability
  • 11:07 – Patching the project to use apt instead of pip for installing virtualenv
  • 12:33 – Forgetting to update the docs and using git commands to fix that
  • 13:36 – Using git add -p to have fine grain control of your git commits
  • 15:26 – Adding new tests to prevent future bugs that are similar
  • 16:48 – Using the -c flag with Python to directly run commands in the interpreter
  • 18:20 – Updating your changelog for the fixes and new additions
  • 19:52 – Testing your changes locally before pushing them to GitHub
  • 23:11 – Manually checking your new test function just to be safe
  • 25:27 – Pushing the changes to GitHub, but not creating a release yet
  • 26:49 – Creating a good git commit using your code editor for syntax highlighting
  • 29:45 – Really pushing it to GitHub after going through a mental checklist
  • 30:40 – Having CI hooked up to your repo is very useful, especially for pull requests
  • 32:28 – Encountering an unexpected error in CI due to a sketchy local testing env
  • 33:39 – Fixing the Python.h related error by installing python-dev
  • 35:00 – Backtracking and changing your mind from a previous commit
  • 37:31 – Moving forward and fixing the error that happened in our CI test
  • 39:28 – Re-running your local tests just as a sanity check
  • 40:23 – Fixing file permissions related to WSL making everything 755
  • 42:48 – Mentally re-tracing your commits before pushing
  • 45:28 – Scoping git add -p to a specific file
  • 47:21 – Pushing our 3 local commits to GitHub and checking Travis-CI again
  • 48:17 – Configuring Travis-CI to run your tests on a regular interval
  • 50:58 – Creating a proper release with the changelog and git tags
  • 53:54 – Updating the Ansible role on the Ansible Galaxy
  • 56:17 – Closing the issue and informing the issue submitter it’s been fixed
  • 56:58 – Dealing with the Earth shattering reality that you pushed a broken release
  • 58:23 – Dropping support for Ubuntu 16.04 LTS since it’s been EOL for a long time
  • 1:01:19 – Deciding not to push a 2nd new release since it affects so few cases

What was the last open source project you updated? Let me know below.

Never Miss a Tip, Trick or Tutorial

Like you, I'm super protective of my inbox, so don't worry about getting spammed. You can expect a few emails per month (at most), and you can 1-click unsubscribe at any time. See what else you'll get too.