Lots of people who work on open source projects, or weekend projects, often don't do software releases. Instead, you'll just commit to main and leave it at that. But should you package everything up, and ship a 'release'?
What even is a 'release', and why is it important? Let's look at each topic individually.
What is a 'release'?
Before we go on, I want to point out that we're specifically talking about software releases here, not hardware or physical product releases.
Software releases are a way to package something up and distribute the final working version of that software. This is needed for people to use the software. The end users receive the latest updates, bug fixes, and enhancements. If we’re going to get really technical,
"Releases are workflows for shipping software to end users. Releases are first-class objects with changelogs and binary assets that present a full project history behind git artifacts."
This is from Rick Olson, in a blog he wrote in 2013.
Shipping software
He specifically mentions releases as a way for end users to consumer the product. In the past you might remember software being shipped in boxes like this:
Image: We and the Color
Video games were also shipped like this and some still are today in the form of disks or cartridges.
You can also consume software in the form of executables, downloaded from websites or even from installers like the Xbox App, Epic Store, or Steam. Then there's the command line which can be used to install things like npm:
npm install -g npm
Types of Software
There are many different categories of software, however it can all be distilled down into two main types:
- Applications
- Libraries
Applications are things that consumers "use". You can also think of them as programs: phone apps, desktop applications etc. Examples include Windows, Elder Scrolls Online, or OBS.
Libraries by contrast are something used to build something else, such as Frameworks, platforms, or developer tools. Examples include npm, React, or Astro.
These games are examples of applications. Image: Reddit
Software doesn't exist unless it's released
Releases are useful in both circumstances for users to consume the product. But what would happen if we didn’t package things, either as executables, in physical discs/cartridges, or via the CLI. Imagine if we didn’t have software ‘releases’. If if we didn’t package software in this way, people would be forced to consume software directly from the source:
Myles Borins, the Product Manager for GitHub, even said:
"Software doesn't really exist, unless it is 'released'".
Releases aren't really useful things like personal projects, website resumes, or similar. This is because there is not really any software being shipped out or used by lots of people. So let's focus on releases for things that end-users are consuming or using.
Why are releases important?
Releases are used as a method for which you do deployments. This means libraries that people are using or applications that people are installing. Releases are then releases are important, because it's a way of communicating changes, encapsulating what's been 'done', making it easy to consume, and then documenting all those things.
Last year, we did a bunch of user research around around why Maintainers and end users thought releases were a good idea.
We also looked at how people are finding out about software releases, and are things like release notes actually important.
Image: UX Indonesia
What our research showed is that in some cases, developers don't contribute to open source projects unless they do releases. But even for consumers this is really important. Ie. OBS if you don't release the code it doesn't go out there and no one can use it; since users would be forced to clone a repo and manually install it, it's not very user friendly, especially for non-developers. Thus developers want to contribute to something that's actually used.
Where do consumers find out about software?
One of the things One of the first things we looked at is how do developers or users get information about latest software releases? How do they know what the biggest and best things are to use, what's cool, what's trending, and what they should check out.
Turns out a lot of people get their information from various news and social media sites:
This also includes things like conferences, and user groups. There's also a handful of people who are actively looking at releases on GitHub, either via the trending tag, their own GitHub watch & notification settings, opt in emails, and the GitHub feed.
By packaging releases and shipping releases alongside good release notes, you’re more likely to get people actively trying the product and using it. We also validated our hypothesis that developers read software releases in order to help them decide whether or not they should use the software. If users are already using the software, then they read releases to decide whether they should upgrade or not. There's a lot of users who spend time reading the notes:
For major releases "I would want to do that research to figure out how people are using it. Are there a lot of issues with this release? What do I gain from making this migration? I may hold off on upgrading depending [on the answers.]" - GitHub Star
Some developers said they even crawl through the GitHub issues list to see if anything stands out. Through the research we further validated that developers and consumers found the lack of information around releases frustrating and confusing. This will often cause them to shy away from the product altogether. During our research, developers and users pointed out some of the key things they like to see in release notes.
Good release notes
What makes for good release notes is mainly context and lots of details about the release. Based on the research we did, we identified some key characteristics of good releases:
- *Why:" was the project changed/updated, is anything likely to break if not updated?
- Summary: and overview of the key changes
- Demos:, examples, and screenshots; anything to make the release more understandable and provide more context
- Attention to detail: using things like name conventions, separating major, minor, and patches
- Detailed Changelog
- Ability to navigate to relevant issues/PRs from the notes
- Migration guide: especially important if an update is required for the software to work
One example of good release notes is Tailwind CSS:
If you want to read more about naming conventions, read this article:
Why should I 'release' my project?
If we take a look at some of the points above, and from the user research, there are a few key reasons why you should release a project:
- Easy to consume the software
- Easy way to find new releases
- If shipped alongside release notes, then provides information
But there are a bunch of reasons why software isn't being shipped out. That's because there are a lot of pain points when it comes to software releases.
Pain points
It’s not just developers and users who can have a frustrating experience with software and new releases. There's often a lot of terrible release infrastructure and processes within companies and open source communities. Another one of the biggest pain points around releases is the release notes.
Image: Abigail Keenan
Some Maintainers even delay or stall their releases because they don't have the time to write up the release notes. This leads to more frustrated user experiences. Several of the people in our study said that keeping track of releases was a manual and cumbersome process. All this adds to the frustration of Maintainers, and leaves them feeling stressed and stretched. Further to this consumers said it also difficult to keep track of new releases, when they are releasing, and what's been changed.
Thus there are two main issues here:
- Developers not getting good release notes
- Maintainers not having the time/energy to do good release notes, combine that with the insanely manual task of actually shipping the release
So GitHub set out to help solve these issues.
What are GitHub Releases?
GitHub Releases are a way to help you with the process of releases for your project.
It's also called Releases Galore. GitHub Releases allows you to upload artifacts, taking a snapshot of your project in time, and providing you with the documentation for that. It also involves automatically generate high quality, configurable release notes for projects.
These are the main things Releases Galore aims to do:
Obviously automatically generated notes won't be able to do all the things above. But this was the most requested feature from Maintainers. Auto-generated notes allows them to automate all the 'boring', basic stuff, so Maintainers have time to be creative and editorial if they like.
Here's a tutorial on how to auto-generate release notes for your project:
The more information you can give to people about the release is better. Thus, this way to auto-generate notes provides a lot of what you need to have good, detailed notes.
Automate
Now you know how to automate and make really good notes. But what about helping you with the release process?
Good news it that a lot of this stuff can be automated. You can automatically publish, push, and ship your release, notes, blog post, and even socials. There are essentially infinite possibilities with GitHub Actions. DEV has a lot of tutorials on how to automatically release your project. There is no one right way to do this. Do what works for your project.
Think how to automate it, and make it easy. Because it's so easy, it means you'll do releases more often.
Top tips
I was recently talking with Myles Borin the PM for Releases, and he gave me some top tips around what he wants to see. You can also watch his video on releases from Universe 2021:
In the interview with Myles, he said that he wants to see more of the supply chain in the field:
I want to be able to see and show the supply chain of open source projects. Releases are a snapshot, an arrow to a point in time where the thing worked. I want people to be good stewards of software.
He says if you're a maintainer of a project, when it comes to releases, don't overthink it! Release often, quickly, and efficiently. Don't do every commit, but release often. Numbers are cheap and even projects like npm do weekly releases.
Borin also wishes people did better Release Notes, and had good consistent release Hygiene. With auto-generated release notes, and GitHub Actions, this is now possible. He encourages maintainers to come up with a good process that works for their project, and then document it.
Ship it
Image: SpaceX
So next time you're updating your project, think about how to get it to your users. Have good release notes, and as much as possible automate it!
Are you working on an open source project that's shipping a major version soon? Submit it to be featured in the GitHub Release Radar.
Top comments (0)