Add note about the changelog entry content for LogAgent #354
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds an important instruction to the LogAgent to ensure that generated changelog entries focus only on user-facing changes, omitting technical packaging details. The change is clear, well-placed within the existing instructions, and directly addresses the goal described in the pull request. The provided example in the description clearly illustrates the benefit of this change. The implementation is correct and I have no further suggestions for improvement.
| IMPORTANT: The changelog entry should focus on user-facing changes only. Do not mention | ||
| technical packaging details such as added/removed patches, changed BuildRequires, | ||
| or other spec file modifications that are not visible to end users. |
There was a problem hiding this comment.
I'm not sure about this. I thought changelog entries should describe what changed from packaging perspective, so exactly the technical details, not user-facing changes. For documenting user-facing changes there is erratum/Bodhi update description.
Packaging guidelines say:
Changelog entries should provide a brief summary of the changes done to the package between releases.
That's a bit vague 😅
Perhaps Miro's point is that mentioning added/removed patches is too much detail, on the other hand when using %autochangelog commit messages describing patch addition/removal would be included in the changelog anyway.
There was a problem hiding this comment.
I personally tend to write short changelog entries for rebases, where it is expected to drop patches, BuildRequires etc. When backporting or doing any other bug fix, I like to write more verbose messages. But overall I prefer more verbose ones.
There was a problem hiding this comment.
No, the changelog entry should be a user-facing change as Laura added. The packaging changes should be written in the commit messages of the commits changing these things. Changelog entry is directly readable for users, as well as the Erratum/Bodhi update descriptions.
There was a problem hiding this comment.
Users can access these data using rpm -q --changelog <pkg_name>
There was a problem hiding this comment.
Perhaps Miro's point is that mentioning added/removed patches is too much detail, on the other hand when using %autochangelog commit messages describing patch addition/removal would be included in the changelog anyway.
When you want to add some message that shouldn't be in the changelog there is a way to do so described here
There was a problem hiding this comment.
No, the changelog entry should be a user-facing change as Laura added.
What kind of user are we talking about? I know Red Hat customers read RPM changelogs, but I always assumed those are not end users, but certified experts/admins who are interested in technical details.
What should be in the changelog then? Only summaries like Rebase to VERSION or Backport fix for CVE-X/BUG_Y?
There was a problem hiding this comment.
I know Red Hat customers read RPM changelogs, but I always assumed those are not end users, but certified experts/admins who are interested in technical details.
Yes, they are, but still, the information about the Patch being upstreamed has zero value for them.
What should be in the changelog then? Only summaries like Rebase to VERSION or Backport fix for CVE-X/BUG_Y
Yes, exactly. Or if some library gets moved to a different subpackage or gets added/removed (this could actually hit them if they use it)
There was a problem hiding this comment.
@nforro do you feel like changing the prompt anyhow, or are you good with going with this?
4 participants
Tried out this with rebase, end ended up with:
instead of the original