Release 4.17.4 #1234
Release 4.17.4 #1234
Conversation
Closes: <shadow-maint#1216> Cc: Chris Hofstaedtler <[email protected]> Cc: <https://github.com/yonecle> Signed-off-by: Alejandro Colomar <[email protected]>
|
@hallyn , would you do the honours? :-) |
|
We should come up with an idea how we want to write changelogs. We have both a NEWS and a ChangeLog file. Neither of which we update. The git commit history is a mess to just drop in as a changefile due to having this ugly Compare this to a git commit with the subject Improve the login.defs unknown item error message. This can easily be dropped in a changelog. Question1: Why do we prefix the dir/file on the git subject line? Additionally we have a billion of commits that are more or less the same just regard different files. Like To have this in separate commits is good practise. In a changelog we would want only one entry for something like this though. Earlier we had nice merge commits. Which could be used exactly for this reason. Question2: Why did we get rid of merge commits? One option could be to write changelogs from hand. Or we could use GitHub or any other tool to let it write them for us. But with our current git history those will only have suboptimal results. The best way would be to have sane defaults so that we can use the proper tools that automate the changelog process. Additionally I think we should create system tests upon each report of a regression like for example #1210 to make sure it doesn't happen again. So my suggestion would be to go back to have merge commits, drop the prefix in git subject lines and generate the changelog automatically upon a new release based on the merge commits. I would also volunteer to edit them by hand to have them in a better state in case automation will not lead to desired results. I think we should unify the NEWS and ChangeLog file into one and just link to the other. In my opinion having a file with just git history isn't necessary and one of those files should just be information for the end user to understand what changed and what to look out for. |
I personally don't find the changelogs useful for myself. If anyone uses them, it would be interesting to know what is expected there. I do still maintain the change log in the Linux man-pages project, which I update manually (every release, I write it in the last commit right before each release, and after the release I move those changes from Changes to Changes.old). If you think that looks good to you and is useful, maybe we could do that. https://web.git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/Changes* On the other hand, I wonder if we could just get rid of changelogs.
When seeing the git-log(1), especially in --oneline mode, I find it very useful to learn the files that a commit touches. It's actively useful to me. Maybe I can reduce the precision of that information, and for example specify only lib/string/ instead of the full path I'm touching. Would that help? I've been doing that in a few cases where the path was too long and not too useful (redundant with the rest of the subject line).
That message, to me, is slightly unuseful. I'd have preferred prefixing it with Also, when investigating a bug, in a git-blame(1) session, I also get some help from the subject prefixes. And it's also useful when we fix a bug, in the Fixes tag, to see what was touched by the commit we're fixing, without showing that commit.
To have an idea of the files being modified in a commit from the subject line alone. The subject line is the only thing I see in
I think I wouldn't even mention those on a changelog. Nothing changes to the end user nor the packager, at all. It's only useful to know for developers, who will see the git-log(1) for that, anyway.
Merge commits occasionally are good. Merge commits as a rule are not so nice, and clutter the git-log(1). I would like to have both options, and decide, depending on the PR itself. For PRs that introduce many commits, I think we should do merge commits. For small PRs, not.
I prefer writing them by hand, or not writing them at all. Automated changelogs are useless, and one should instead parse the git-log(1) for the same info.
Feel free to contribute them. I don't have time for that, and honestly, I don't enjoy writing them as much as I enjoy simplifying code. I don't even understand python and the new framework for tests. And I wasn't confident running the old shell test suite either, nor understood it well either. I have a queue of 200 patches at the moment, enough for a year of reviews. If I start writing tests for all of them, that will grow significantly, so we'll finish merging them by 2030. :)
I'd appreciate being able to do merge commits, and do them by hand (so pushing from the terminal, not just a generated merge commit from github), so I can make them informative. I would use them selectively, though. And we should make sure we rebase stuff often (not neccessarily always) to not create a mess of a git-log(1). I don't agree with the subject prefix, as it's useful to me. I'll try to keep it short, in cases where a full path might hurt too much. I refuse to have an automated changelog, but a manual one, if it's useful to you, I don't know. What do the others think? I'd just remove the changelogs and the news files. I appreciate if you'd contribute tests. That would be useful.
Yep, one should be removed. Probably the ChangeLog I'd drop it. The NEWS file might be interesting to note important stuff. I don't think linking is a good idea, though. It's better to remove it. And let people interested in the old changelog to find it in the git history, but not in the working tree. |
This comment was marked as resolved.
This comment was marked as resolved.
Because you are not a packager/distribution maintainer ;) They need to know:
They usually don't need to know details about implementation. Until they suddenly sometimes do. Which is why the issue number or PR number from a merge commit would be helpful to read up on those details. Both the details of the discussion and seeing the individual commits.
The discussion about having automated or manually written changelogs is as old as having projects. There are various pros and cons. I listed above how to have them automated. |
These contents seem reasonable, and are what I include in the Linux man-pages changelog. We could do that.
When releasing versions of the Linux man-pages I usually take half an hour (or a couple of hours if the release is really huge) for writing it. I wouldn't mind doing it myself. I can take a similar approach. Whenever we want to release, I can do the work on the Changelog. Let's start with 4.18.0 for that? |
We stopped using and updating those files some time ago, and I'd prefer to keep it that way. Those files are there for history purposes. Having said that, I agree that we should have some kind of release notes that are helpful for the audience (see below).
The important topic here is the audience. git history is mainly used by developers, and I agree with Alejandro that having those type of messages is helpful for this type of audience. And now if I switch my hat to a distribution maintainer, I agree that those messages aren't very useful. Maybe the developers should try to improve the commit body message so that other people apart from themselves understand what is happening.
The release notes should be informative for a more general audience, like distribution maintainers and sysadmins, so I agree that they should contain more information about the actual issues fixed in a given release. I would also like to have good release notes and have them created automatically. If you have any ideas on how to achieve this feel free to propose it.
As a final note. I completely disagree with having tests for each regression. I've worked in several projects where this happened and test maintenance was a nightmare. I'd prefer to have comprehensive tests where the most common use cases are tested. If some corner case is missing, that's fine, as long as the general use cases are working and users can use the software in their day to day. |
|
On Tue, Mar 04, 2025 at 04:20:08AM -0800, Iker Pedrosa wrote:
We stopped using and updating those files some time ago, and I'd
prefer to keep it that way. Those files are there for history
purposes.
Having said that, I agree that we should have some kind of release
notes that are helpful for the audience (see below).
But should the release notes go into a file in the repository? Or
should they just be attached to the release? (As in the github release
page?) It would be useful to put them into a file (or maybe in the
message of the release tag, when doing 'git tag -s'.
The important topic here is the audience. git history is mainly used
by developers, and I agree with Alejandro that having those type of
messages is helpful for this type of audience. And now if I switch my
hat to a distribution maintainer, I agree that those messages aren't
very useful. Maybe the developers should try to improve the commit
body message so that other people apart from themselves understand
what is happening.
I think for distros, merge commits would be more interesting to read.
They should contain a resume of what was discussed during the review,
and give an overview of the changes.
The release notes should be informative for a more general audience,
like distribution maintainers and sysadmins, so I agree that they
should contain more information about the actual issues fixed in a
given release.
I would also like to have good release notes and have them created
**automatically**. If you have any ideas on how to achieve this feel
free to propose it.
In the Linux man-pages project, we had semi-automated release notes in
the past. But I changed them to fully manual ones, and I like more the
current approach. They tend to be more curated and informative. And
the amount of work is similar.
> Additionally I think we should create system tests upon each report
> of a regression like for example #1210 to make sure it doesn't
> happen again.
As a final note. I completely disagree with having tests for each
regression. I've worked in several projects where this happened and
test maintenance was a nightmare. I'd prefer to have comprehensive
tests where the most common use cases are tested. If some corner case
is missing, that's fine, as long as the general use cases are working
and users can use the software in their day to day.
For a small project, like for example liba2i, I do have regression tests
for every bug that we have found, and being a small project, it's
manageable. Since the API is stable and simple, I don't expect to add
many more regression tests in the future (hopefully, none at all).
If we externalize some dependencies, like liba2i and libstring, we would
get rid of a significant amount of code, and with it the responsibility
to test it. If that happens, the shadow utils code would become much
smaller, and with it, we could maybe put more focus on testing the
remaining parts.
But, I don't expect that before 2030 (and most likely, later than that).
…
|
Release notes or News file - basically I don't care. But since the file already exist and had such a purpose.. Why not use it?
As mentioned above by devs vs maintainers/distributions.
Which I just did in the comment above :)
That's interesting, what exactly was a nightmare? I can't see any downsides and thought the purpose of tests is to make sure functionality is as expected. |
I'd say most people read Github release notes page. If anything.
Right, I don't know I wrote that.
The sheer number of tests is the problem and the little value they provide. Since we are working on shadow let me show you test example that was written a LONG time ago and that we currently run to test our distributions: This test was created to test https://bugzilla.redhat.com/show_bug.cgi?id=177017. In my opinion, the value of this test today is almost nil. From a more theoretical point of view, a feature like useradd would need thousands of tests to be fully tested. Given that it is unlikely that we will ever have that many tests, and given that we have users using this feature every day it is quite likely that someone will come up with the extraordinary idea that the ID can be a set of alphanumeric characters. Example: I hope you understand my position on creating regression tests for all cases. I am not saying that regression tests should not be created, just that we should use our heads before creating them because this part is usually easy but then maintaining them during the years that the software is used is another matter. |
|
For the kind of thing @jubalh is asking for, I don't think spending a few hours at release time is the best way. It would work better to try and get PRs to update the changelog when they do something a package maintainer would want to know. The trick of course is how to know when that's the case. That, and then I start feeling like people who's changes aren't called out will feel slighted :) So I end up just doing 'git shortlog', because actually I think that does pretty well. |
That would add more friction to the PRs. For example, GCC does this in the commit messages, and I find it very cumbersome to update the changelogs correctly. In their case, it's fair, since their releases are huge, and updating the changelog at release time wouldn't be doable.
Yep, that's a thing. I try to make it objective:
Otherwise, I tend to not mention it. Unless for some reason I make an exception. Exceptions break that objectivity, but hopefully not too much. Also, I add a few lines saying that there are changes not mentioned there, but that are present in the release. Example from this morning, from the release of man-pages-6.13:
I'm okay if you prefer that. But if we go that way, my only ask is that the changelog file not be updated. I'd keep that only in the release notes. |
|
Yeah, that's what I'm doing, putting it in the release notes. If you're already clickity-clicking in the github webui, I think that's a lot easier than alternatives. |
Closes: #1216
Cc: Chris Hofstaedtler [email protected]
Cc: https://github.com/yonecle