You Should Use Releases on GitHub

As I mentioned in my previous post, I have decided to write 52 posts on dev.to in 2023 publishing one every week, this is the first post.

All of my projects have a change log, a single file in Markdown or text included in the repository. Based on these I write release announcements, which I post on dev.to. My change logs are a sort of collection of changes and I try to put as much information into my change logs as possible without making them unreadable. The most popular post I ever published on dev.to was on how to structure a change log for a software project, you could give that a read if you want to tap into how I approach this.

My release announcements are a tad more rich, since I want to translate the concise change log format into a story and describe the process, reasoning, experience creating a particular release and I post these on dev.to both for promotion, but mostly for reflection and collecting my thoughts for getting closure on a particular phase in a projects life-cycle before continuing to the next phase.

In this post want to revisit this particular topic, but narrowed down to working on open source projects hosted on GitHub. Some aspects might be applicable elsewhere, but this is coincidental.

Change logs are all about communication. You could retrieve the much of same information from a Git commit log and/or inspecting a GitHub repository. Git commit logs do however often also other things, which would clutter the communication, since the granularity is very high and many commits in collection boil down to a basic or single feature or bug fix, something only taking up a few lines in a change log - but lets skip that problem for now and get to the main topic.

I want you to make releases on GitHub

GitHub supports a concept called releases. They are a sort of highlighting of the code at a certain point in time and they point to a regular Git tag. It is not a new thing and many repositories use them, but some do not, which is most unfortunate.

The releases on GitHub. as I see them, are a supplement to the change log. One could argue that you do not need a change log, but I just keep one, so it can accompany for example my Perl distributions and it can be read and used elsewhere, even when users do not have access to GitHub.

The goal is to communicate clearly that the release described in the change log has been made. You could blog about it, which I can only recommend, since this works for me personally, but that might not be your thing and I might not be knowledgeable of your blog, but there is a more convenient way - an opportunity generated by making releases using GitHub.

Making releases on GitHub is manual labor and I understand why some open source maintainers are reluctant, since all the changes are in the Git log or in a change log file in the repository, but as I user/consumer of your work, I do not necessarily know that things are being updated.

When you are on you repository page on GitHub and on the "Code" tab. The releases, if enabled, are in the right column. You can suppress this by disabling "Releases", which are enabled by default, but I really do not want you to, I want you to use this particular GitHub feature.

What I normally do when I create a release for one of my repositories it to gather the notes in the change log file. I tag the project in Git, make sure every thing is pushed and that all tests are passing. Then I create a release in GitHub. You can delete both a release and tags if need be, so it is not a feature you should be afraid to use.

I copy the relevant section from the change log file into the release announcement, describing the changes since the last release, associate my release with the latest tag and publish.

A foot note: I can recommend writing you change log in Markdown, then you can easily copy it into the text field in the GitHub release UI.

There is not much too it, it is manual and it is not particular exciting. What it enables is much more exciting.

I want you to inform me - the user, of your release

Many of the releases I make a are based on updates to the dependencies my projects rely on. Oftentimes it is bots that send me a PR, but this is more often in relation to security issues, so the normal updates to my dependencies have to be spotted and handled manually, not something I mind, after all I am an open source maintainer, BUT it is not easy to keep on top of different toolchains, libraries etc.

However, when if you take a look at a GitHub repository page. There is an option to "Watch" in the top-right menu.

The allows me as a user to decide on a notification scheme for YOUR repository. On my own repositories the default setting is: "All activity", but for projects where I have no involvement, I am an external party. I do not necessarily contribute, often I just use - as a GitHub user I can select "Custom" and under the "Custom" menu point I can select "Releases".

This mean I will receive a notification every time a release of this particular repository is made.

When I receive this notification I can decide on whether this is something I need to handle. Do note I also subscribe to the "Security Alerts", so I am aware if my software is using an insecure dependency, but that it another story, which require another post at another time.

The challenge here it so get open source maintainers to use the release facility offered by GitHub and yes it is hard work, but as a consumer and user the benefits are clear since I am notified automatically and if the release description is good, I can based on this alone decided on whether I need to follow up with updates, changes and my own releases.

GitHub are now offering automatic generation of release notes, which could be eliminating the last obstacle to start using the GitHub release feature, since the manual process could become easier. I will end this post here as sort of a cliffhanger and one of my upcoming posts will be on how to automatically generate releases notes using the GitHub release facilities.

Thanks for reading, comments and feedback most welcome.