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.
Top comments (5)
I admit the title "You Should Use Releases on GitHub" draw me in as it (no offence intended) smacks a little of arrogance - and that puzzles me on dev.to when I see it (which I do from time to time).
For my part, thanks, it's a nice reminder that releases are an option and I like that.
What if overlooks (and this relates to the impression the title gave me) is that rolling-release model of development is very valid and has some enormous traction in the world of FOSS, Entire Linux distros are based on it. And many a FOSS project as well. Many have formal releases and version numbers. But others, work quite well, simply with one master branch, development running on side branches and merged into master when tested and ready for the wild.
Such merges can increment a version number or not, remaining identified by the date alone.
Of course, where end user support, or customer support begins to be a significant issue, release and version numbers facilitate a few important things indeed (helping people identify which version they are using when looking for support for example and grouping these merges into fewer, larger, more significant updates). In the case of a rolling-release product for example there is often no end user support that doesn't start with "Have you pulled the latest release?" ;-).
But methinks one reason projects opt for that is that the rate of change is high, and another is that the hands on deck are few (you rightly identified it's work, releasing a product and if there are barely enough hands on deck to triage issues and develop the software, well, something gives ...). Both of these of course are more common early in the life cycle of any piece of software, and as it (and if) gains popularity and resourcing, to be sure, wonderful things like release management and documentation either pop up or take on more shine etc ...
Hi @bernd
Thanks for you very extensive comment.
First let me say you have some very valid points and I do agree with you, but perhaps I am very biased, being brought up on open source software on a Linux foundation, so I often expect the rolling-release model you describe, which might be a mistake on my side.
But let me add some perspective.
I put open source software repositories into two major groups.
For the first part a rigid versioning scheme is not required from my point of view, it is nice. But as you state it, a main branch with transparent updates works just fine.
As for the other part, I often need to express/state my dependencies very clearly and often in dependency description files which can be resolved by my toolchain for easy installation etc.
Since modern software is very much comprised if dependencies, as opposed to writing everything yourself and since we have resolved the challenges of distribution and sharing, we are building software which is relying heavily on external components/dependencies - this brings forward a lot of challenges.
Personally I spend a little time on keeping my project dependencies up to date and all I request is for the developers/maintainers to lend me a hand, when they make releases - but I can make it even without these extra efforts. My worries are mostly centered about: toolchain attacks and becoming the weakest link in the chain, so I have an incentive to keep my projects updated.
From a professional perspective I am a bit more concerned and leaning more towards a more rigid regime and that might be what is shining through in my post.
Many companies today is using and building on open source software, which is great. But with that comes the requirements of compliance, licensing etc.
I am currently evaluating tools from companies like:
Which could help me in mapping out use of open source software, use of licenses etc.
These companies and their tools are dedicated towards this particular problem area and they have the resources to poll all the relevant repositories and might not be dependent on for example release notifications, which I see as more of an event based schema, compared to just polling all known repositories.
These tools however do not come cheap and small shops do not necessarily have the resources to poll all of the dependencies like these dedicated companies, so instead of polling all of this information, it might prove more interesting to use an event based flow, like release announcements.
As for the rate of updates/releases, that is a different challenge. I just signed up to following react-admin, boy these people are active. Which is good and it keeps us on our toes, luckily they use GitHub releases which makes it easier for us to keep up.
As I see it, the problem of keeping is not going to go away. Personally I am not so concerned for my small side-projects, professionally I believe this will only become a more inevitable challenge, that in the end we might have to though money after.
I have a final question to you, just as a thought experiment:
Not at all. Thank you for a solid article and friendly response to feedback.
As to your final question I'd just tone down the hype a little. You see I find hype interesting it sort of evolved in an era of media (latter half of the 20th century) as a marketing tool, to grab peoples attention. By hype, I refer to exaggeration, superlatives, imperatives and such used in headlines and announcements I guess.
Alas, IMHO, the world has evolved a little. We went through a fascinating period in the evolution of the World Wide Web, that many of now think of the "upworthy" era. Upworthy was a flash int he pan, huge phenomenon on-line, flooding information and sharing channels. But they had this incessant habit of hyping up all their headlines and we saw a rapid response with downworthy browser addons that would strip the hype from web pages:
downworthy.snipe.net/
And I guess in my view the professional world has reacted by holding hyperbole in mild disdain in technical articles since.
Yours is not even bad. Better hype would have been "You must use releases on GitHub" or "You'd be crazy not to use releases on Github" or "No serious coder would ever fail to use releases on Github". It's actually quite fin playing with spin and hype.
But if I had written or reviewed (as an editor prior to publishing) your article I guess I'd have opted for a softer title ... like "Using GitHub Releases Effectively" or "Easy Release Management using GitHub Releases" etc.
I guess descriptive rather than imperative.
I agree on the use of releases within GitHub. What I do disagree with is the statement of it being complex, or a manual process. The owner of the repository can create their own workflows that trigger off of a new tag. To then create a release complete with release notes. And if you don't want to recreate the wheel there are several GitHub actions to help within the workflow.
Hi @ndrone
First of all thank you for your comment.
I agree with you on that it is doable. And I am happy that you say that it is not complex, which gives me hope.
I do however believe that complexity is in the eye of the beholder, so the moment you have understood or unraveled something complex it often seems less complex. So propelled by your comment I am motivated to dig in the complexity and hopefully emerge on the other side, educated and with improved automation.