Skip to contentSkip to conversation

A walkthrough of some of the challenges with auto generated changelogs

DISCUSSION Richard Purdie 2 participants 4 messages Sep 2 – Sep 7

lore
Share & tools
lore
#0 lore raw

Everyone keeps telling me how great these auto generated change logs are and yes, they can be helpful but they are also piling pressure on me as everyone has their own preferences and personal "triggers" for issues. I keep getting told how XXX shouldn't have merged without YYY being tweaked but the tweaks/triggers vary per person. I also get told a changelog is better than none and that we shouldn't be spending time on it. I can't win.

I'm feeling bad that I haven't written down the things that are causing issues so I'm now trying to do that here.

One general issue is that we can often delete the "Source: ZZZ" lines. They're good to explain where the data came from, we don't need to keep them in the final commit message in most cases (unless they're urls?).

Taking some recent examples of other tweaks that need to be made:

"appstream: upgrade 1.1.6 -> 1.2.0"

This one has a truncated log. We added a test to patchtest to warn about that, patchtest warned but it is still queued. At least one manual review missed it too. We may want to up the auto-truncate limit slightly.

"python3-pdm: upgrade 2.28.2 -> 2.29.0"

This as a github changelog. These are more readable/shorter if you strip out all the github PR links. We really don't need them. It also needs linewrapping. If someone doesn't linewrap it manually, I get complaints.

"libksba: upgrade 1.8.0 -> 1.8.1"

This has a lot of noise in it and isn't well formatted. The commits hashes, dates and people can be stripped down. It can be reduced to one or two lines.

"re2c: upgrade 4.5.1 -> 4.6"

github pull request link can be dropped

"librepo: upgrade 1.20.0 -> 1.21.0"

Are the prefixes with the commit hashes useful? Should those prefixes be stripped?

There are probably other issues but those are probably the most common tweaks I've been making.

So in summary:
- could/should the Source: be after the scissors if non-url?
- can we strip out the github urls for pull requests?
- can we linewrap the data better?
- can we drop commit hash refrerences?
- should the truncation limit be slightly higher?

Cheers,

Richard

#1 lore raw

Hi,

Thanks for the input.

Quoted 7 lines · Richard Purdie

Everyone keeps telling me how great these auto generated change logs are and yes, they can be helpful but they are also piling pressure on me as everyone has their own preferences and personal "triggers" for issues. I keep getting told how XXX shouldn't have merged without YYY being tweaked but the tweaks/triggers vary per person. I also get told a changelog is better than none and that we shouldn't be spending time on it. I can't win.

Maybe I should write a proposal on what to include in the commit messages regarding the changelog changes?

My opinion is also the latter. A changelog is better than none and that we shouldn't be spending time on it. There is always the original changelog if people is interested in all changes.

The original intent was for the stable releases, where is more important to know what has changed.

Quoted 7 lines

I'm feeling bad that I haven't written down the things that are causing issues so I'm now trying to do that here.

One general issue is that we can often delete the "Source: ZZZ" lines. They're good to explain where the data came from, we don't need to keep them in the final commit message in most cases (unless they're urls?).

I'll create a patch for it for the AUH to truncate it, so we have both. That should be simpler.

Quoted 36 lines

Taking some recent examples of other tweaks that need to be made:

"appstream: upgrade 1.1.6 -> 1.2.0"

This one has a truncated log. We added a test to patchtest to warn about that, patchtest warned but it is still queued. At least one manual review missed it too. We may want to up the auto-truncate limit slightly.

"python3-pdm: upgrade 2.28.2 -> 2.29.0"

This as a github changelog. These are more readable/shorter if you strip out all the github PR links. We really don't need them. It also needs linewrapping. If someone doesn't linewrap it manually, I get complaints.

"libksba: upgrade 1.8.0 -> 1.8.1"

This has a lot of noise in it and isn't well formatted. The commits hashes, dates and people can be stripped down. It can be reduced to one or two lines.

"re2c: upgrade 4.5.1 -> 4.6"

github pull request link can be dropped

"librepo: upgrade 1.20.0 -> 1.21.0"

Are the prefixes with the commit hashes useful? Should those prefixes be stripped?

There are probably other issues but those are probably the most common tweaks I've been making.

Quoted 6 lines

So in summary:
- could/should the Source: be after the scissors if non-url?
- can we strip out the github urls for pull requests?
- can we linewrap the data better?
- can we drop commit hash refrerences?
- should the truncation limit be slightly higher?

The last one should be easy. It is a configuration parameter in the AUH. For the rest, I will look at all the issues that you listed next week, together with what Ross reported a few days ago. I hope I can come up with small patches getting it better. I will probably need to add some heuristics to distinguish between the different cases and hope not break things.

If more people has feedback, please send it to me.

The original intent was to be a help when doing recipe updates and not a burden for you.

Cheers,
Daniel

#2 lore raw
Quoted 14 lines · Daniel Turull

Thanks for the input.

Quoted 7 lines · Richard Purdie

Everyone keeps telling me how great these auto generated change logs are and yes, they can be helpful but they are also piling pressure on me as everyone has their own preferences and personal "triggers" for issues. I keep getting told how XXX shouldn't have merged without YYY being tweaked but the tweaks/triggers vary per person. I also get told a changelog is better than none and that we shouldn't be spending time on it. I can't win.

Maybe I should write a proposal on what to include in the commit messages regarding the changelog changes?

Quoted 6 lines

My opinion is also the latter. A changelog is better than none and that we shouldn't be spending time on it. There is always the original changelog if people is interested in all changes.

The original intent was for the stable releases, where is more important to know what has changed.

Agreed, it definitely is useful but I did want to make sure people could see the other side of this too. None of this was meant as critisism, more just open feedback on how it 'feels' having used it for a while. Some of the implications are not quite what I'd foreseen.

Quoted 9 lines
Quoted 6 lines

I'm feeling bad that I haven't written down the things that are causing issues so I'm now trying to do that here.

One general issue is that we can often delete the "Source: ZZZ" lines. They're good to explain where the data came from, we don't need to keep them in the final commit message in most cases (unless they're urls?).

I'll create a patch for it for the AUH to truncate it, so we have both. That should be simpler.

Ok.

Quoted 13 lines
Quoted 6 lines

So in summary:
 - could/should the Source: be after the scissors if non-url?
 - can we strip out the github urls for pull requests?
 - can we linewrap the data better?
 - can we drop commit hash refrerences?
 - should the truncation limit be slightly higher?

The last one should be easy. It is a configuration parameter in the AUH. For the rest, I will look at all the issues that you listed next week, together with what Ross reported a few days ago. I hope I can come up with small patches getting it better. I will probably need to add some heuristics to distinguish between the different cases and hope not break things.

Quoted 4 lines

If more people has feedback, please send it to me.

The original intent was to be a help when doing recipe updates and not a burden for you.

No problem, as I said, this isn't meant as critism and I am trying to give some hints on where/how it could be improved. I appreciate some of the suggestions aren't easy (and hopefully some are). Thanks for working on it and looking at the tweaks!

Cheers,

Richard

#3 lore raw
Quoted 19 lines · Richard Purdie
Quoted 18 lines · Daniel Turull

Thanks for the input.

Quoted 7 lines · Richard Purdie

Everyone keeps telling me how great these auto generated change logs are and yes, they can be helpful but they are also piling pressure on me as everyone has their own preferences and personal "triggers" for issues. I keep getting told how XXX shouldn't have merged without YYY being tweaked but the tweaks/triggers vary per person. I also get told a changelog is better than none and that we shouldn't be spending time on it. I can't win.

Maybe I should write a proposal on what to include in the commit messages regarding the changelog changes?

My opinion is also the latter. A changelog is better than none and that we shouldn't be spending time on it. There is always the original changelog if people is interested in all changes.

Quoted 9 lines
Quoted 3 lines

The original intent was for the stable releases, where is more important to know
what has changed.

Agreed, it definitely is useful but I did want to make sure people could see the other side of this too. None of this was meant as critisism, more just open feedback on how it 'feels' having used it for a while. Some of the implications are not quite what I'd foreseen.

No worries. I took it at as open feedback, not criticism.

Cheers,
Daniel

Quoted 1 line
Quoted 1 line