The title is a little cryptic. But let me explain.
When users report bugs, we submit a github issue with a title. And if the person is normal or near normal, the title will be a fair short description of the problem.
Example: I submitted enigma2 “integration fails to start and flood log after upgrade to 2024.1.0”
The workflow on the project is that a PR is created. And in many many cases the fix is to update a version of a dependency. The title of the PR is usually something like " Bump openwebifpy to 4.0.4"
It is the headlines of the PRs that end up in the release note.
This is where the Bumping is not user friendly comes in. Most patch releases are a list of Bump this and Bump that. You have no clue as a normal user about to upgrade - reading the release note - what it is all about. Unless you know that the name of the Python dependency could be related to your problem, you have no idea. It is just bump after bump.
Now we could ask the release manager to spend time writing a proper release note. But that takes an awful lot of time investigating each Bump, tracing back to the original bug report and try and write a meaningful one liner.
A much better fix is cultural. Stop Bumping in the titles. The developers doing the PRs know what they are fixing. And it takes no time at all to write a title like
“Fix enigma2 integration from crashing (Bump openwebifpy to 4.0.4)”
Now there are valid cases where you just Bump a library without having a bug to fix but just want to stay up to date. Then the bumping message makes sense.
I would hope more developers will consider to make better and more user friendly release notes by adding 4 to 8 words describing what is fixed instead of only the Bump message.
Happy new year and thank you for all your PRs.
Note: I did not want to single our the Enigma2 developer with this. He/She is doing what all is doing. It has become a culture on this project. I am hoping to influence a small change in this culture and I am sure none of the developers have throught about this.
Users are (rightly) expected to read the release notes to identify anything which may impact our installations. Of course this is normal for any system with active development and a significant level of complexity.
But expecting any non-developer to piece together all the clues to figure out how and if any “bump” impacts them is a lot to ask.
I worked about 8 year on a development unit, phrases like bump, never ended up in the “Public” Release notes, no dev slang did, Release notes should be readable/understandable/easy traceable for integration-engineers, support-team, customers/end-users , so it was "fixed bug(with reference to bug-id and header) whether it just was an updated file-version, or just, updated version to x.x ( if no related bug-reports) etc.
Everyone would, Even Custom Managers … I can imagine If a customer would call their representative , wondering if the fix for a specific bug is in the new release … ehhh, yeah maybe it’s bumped already … hold on , i just have to go through 4 dozen bumps … No he/she doesn’t, they in term calls the Support Team, whom in worse case call/walk down to the Dev team, as no bump’s was directly “pinned” to the specific bug-report.
Well anyways , as Kenneth also point out, some, maybe quite some “bumps” is just file-version updates, which in many cases don’t even have to be “specified” in a Public Release Note, if it aint affect current Product/Software-version, in either ways ( meaning it doesn’t really matter if it’s 1.1 or 1.2, everything related works as usual ) no actually need for others than the Dev’s to know ( as an integration-engineer ( most ) usually check such , if they are in “the area” or that “level”, of a file-system, and they need a certain version, for their customization/integration
It’s even worse when there are bumps, followed by reverts. Because then you have a chain you have to follow, to see if something really did eventually get updated, or if it was updated, and then downgraded again.
FYI, zha integration and zwave_js integration also examples where each bump usually contains multiple changes and multiple fixes (which are sometimes linked and sometimes not) + some bumps contain several different dependencies in a single bump :
I think I would be happy to read “Multiple fixes to ZHA”
What the end user really needs to know is if the release will fix an issue that he/she has and if it is multiple then the limit of 1 lines would make a general term OK. The problem with Bump messages is that they refer to a library name and they are often not the same name as the Integration. Only developers knows what they are. I really do not want to add burdens to the developers. Just simple awareness on the end users need of the release notes.
Maybe if the bump didn’t fix a specific issue it could be omitted on the full changelog in the blog. In case that a user really wants to know the nitty gritty details then he could go to Github for the comprehensive changelog.
No. The users need to know what is changed in a human readable format. Github is a developer tool and you really need to know both Github and the developer process specific for Home Assistant.
It is not the word Bump we are addressing. My goal is to make the release note user friendly for non developers.
We have excellent release notes today. It is just the little details with the bugfix PRs listed where the fix is simple. If the developer culture or tradition could change so that the one liner title would describe what is fixed instead of which Python dependency is upgraded. That should not require any extra effort.
I’ve always had the question - from the early days of using bump when I managed developers: Are you doing it sooner or later than expected? Many times ‘bump’ referred to a bug item being pushed to a later date, as in “bumped off the current list”. I guess it has evolved quite a bit since then. I’m glad you posted.
I’ve also had that experience , working as system/support engineer for a development unit, in this context it mend as you describe “moved to” OR “postponed” if you like ( Customers would say that )
In other contexts the “Word” could also mean “moved up in the list” ( i.e lifting/highlighting a case/bug to higher Attention" )
And apparently here it’s also used in the “meaning” of “Fixed” or “updated to newer version”
Which in my Opinion clearly says/shows that such a “word/slang” should Never be used in a Release Note !
A Release Note should Not use words/slang which can be interpreted in so many deviating ways
( one can make a simple google search, to see in how many different ways the word “Bump” is used / means , in various contexts )
It’s totally up to the “writer/development team” ( in this context ) to decide what they put into the Word, which makes it totally not a word for a public Release Note.
If a non-tech/non-dev person Bump into this word, they wonder !, and if they google the word, they would wonder even more !
So in short, someone just found this word “cool” to use, in the HA-Github, dev-repo, and somehow it also ended up in the “Public” Release Note, addressing a huge variation of People, with alot different experience of the use(and meaning) of the word “Bump/Bumped/Bumping”
If the developers replaces the slang “bump” to the formal “Upgrade” it will help the users very little.
My posting suggests that developers descrive in one line what is being fixed and not which library is being upgraded - when the upgrade of a library is done to fix a problem.
There are many cases where you upgrade a library just to keep up to date and prevent future bugs. In those cases I am fine with a Bump message.
But more than half the release note messages about bumping originates in resolving bugs. The end users would have much better use of a message that says a problem they have faced has been resolved.
Many users downgrade to an older version because of bugs, and they really can use the information that a bug in the affected integration has been resolved. It would be a signal to try to upgrade HA again
Yes, i know what you mean, and suggest, and i agree
After i posted my “latest” commend, i was thinking that i had actually posted almost the same thoughts already ( and yes i also fast got used to the “Bump” , when it just seemed to be an “latest” version upd. ) (thou i did at first thought it was something they “skipped” , i.e bump version-1.1 == skipped(jump over) version-1.1 (for unknown/irrelevant reasons)
And i can’t say, or think of why Dev’s have/had a habit of “skipping” info, in regards to which i.e “bugs/features” an “updated/versioning” fixes, other than they have previously been a relative small team, addressing a relative limited “crowd/audience” , and so with the “expansion/popularity” and new goals, more and more audience, i guess they haven’t giving it a thought( cause they have “always” done it like that )
If you look at a PR and it’s a ‘bump’, there’s a required field that points to bugs that a PR is fixing. If that field is not filled out, then it’s a rev bump fixing nothing. Basically what you describe as:
It is all about the release notes and not the PRs. Surely developers look at the PRs and know what pysomething is. But I would hope the release note most of all is targetted the majority of users that are not Python programmers. It does not cost any extra effort to write a headline that describes the problem fixed. I only ask the PR submitters to think about it. And if you forget, then thank you for the work and the fixes anyway.
The PR’s are listed in the release notes (blog post, release, whatever you want to call it) under all changes. The info you’re requesting is there as long as the developer filled out the form properly.
Example of a dependency update required by some library
Example of a upgrade including what updated and full links to other release notes
All accessible from the release notes of the current release.
Just do a CTRL+F and find the word bump, I’m sure you’ll find all examples. But what your asking for is already in place and is a requirement. Whether developers fill that out properly is only caught by reviews and some things can be missed.
I was about to say something similar as Kenneth , yes true it’s all there, maybe you not picked the “best” example, but you surely showed/proofed how cumbersome it could be , i.e for a not so techy or github familiar person or , i.e average users .
There are lots of other examples, even in this release, where the “initial” release/blog ( And the more detailed) , where it’s just " xyzq.py Bump to version X " , spite in fact it’s a bugfix( or part of )
I could name not a few as examples, but won’t, as i then have to post not only pics of the various examples, but also pics of the fact it’s a “Bump” to fix Another issue , with another Reported bug number" etc. ( Which btw is Not reported as Fixed in the release !)( In other words than " xyzq.py Bump to version X "
Yes it’s a complex “structure” and many “fingers/minds” involved in the Repo, But what "Average/Most People, would like to See is just i.e Fix for XYZ,
People GAS whether it’s XYZQ.py bumped to/upgraded to , Specially if it’s just to Fix XYZ
( I DON’T Underestimate the Dev’s work, it’s tremendous ! )
I don’t even wanna count the “BUMPS” in the “Blog-Post/Release”, Nor the Detailed list
So If i.e some xyzq.py is “Upgraded/downgraded” or bumped, doo to a Bug, it would be easy to just skip the " bollock.py " and write i.e " FiX/Enhancement for SNMP/Trackers " , because anyhow , it leads to a bunch of other Bumps/Bug-Reports etc. etc. ( As you show above ) for the people who needs these details (for what ever reason)
( Search and Find )
… I can imagine If a customer would call their representative , wondering if the fix for a specific bug is in the new release … ehhh, yeah maybe it’s bumped already … hold on , i just have to go through 4 dozen bumps … No he/she doesn’t, they in term calls the Support Team, whom in worse case call/walk down to the Dev team, as no bump’s was directly “pinned” to the specific bug-report.
)
