I think we should post devmanual-commits emails to the gentoo-dev ML to ensure devs are kept up to date on changes. Even if it's slightly noisy at times during refactoring, I think it's much better than nothing.
This came up earlier in #gentoo-dev when discussing the repoman/pkgcheck migration, but it's been on my mind anyway as a method to keep folks informed. "We updated the devmanual, it's been there for a while" etc isn't a very helpful comment because I don't think developers are really going to be re-reading every page weekly or monthly or something. Notably, slyfox also mentioned this kind of thing in his leaving post: https://trofi.github.io/posts/226-farewell-gentoo-dev.html.
(In reply to Sam James from comment #1) > This came up earlier in #gentoo-dev when discussing the repoman/pkgcheck > migration, but it's been on my mind anyway as a method to keep folks > informed. > > "We updated the devmanual, it's been there for a while" etc isn't a very > helpful comment because I don't think developers are really going to be > re-reading every page weekly or monthly or something. > > Notably, slyfox also mentioned this kind of thing in his leaving post: > https://trofi.github.io/posts/226-farewell-gentoo-dev.html. My only objection is primarily a pre vs post merge. E.g. ideally you'd make a PR against the devmanual and post that patchset to the list, and then after a while, merge it. If you think no feedback or comments are going to happen on those threads, a post-merge hook is a 1 line config change...but now you are left with dev community that learns about changes post-facto, rather than being involved in them. -A
That's a good point. I'd suggest that patches to the devmanual should go to gentoo-dev@ for review.
I'm somewhat against the idea as it may be seen as "spam" because I believe there's just a few people interested about this documentation effort, and these people already know how to get involved. But I can imagine something similar to be fine as the "automated package removal and addition list" mails. https://bugs.gentoo.org/795492 So you'd do something like this: April 1st 00:00 UTC: Subject: "Monthly devmanual updates: 2022-03-01 - 2022-03-31" Message: keywording: it's preferred to rekeyword packages with new deps 2022-03-10 23:33:17 876646b ebuild-writing/eapi: update link to Python guide 2022-02-25 19:02:45 9ee6fa ebuild-writing/eapi: mention blocker retention period 2022-02-22 07:11:27 ed8d22 ebuild-writing/eapi: document upgrade path policy 2022-02-22 07:11:24 2da338d ... https://gitweb.gentoo.org/proj/devmanual.git/log/ (maybe even link the detected updated pages here, such as: https://devmanual.gentoo.org/keywording/ https://devmanual.gentoo.org/ebuild-writing/eapi/ ) (In reply to Alec Warner from comment #2) > > My only objection is primarily a pre vs post merge. E.g. ideally you'd make > a PR against the devmanual and post that patchset to the list, and then > after a while, merge it. > > If you think no feedback or comments are going to happen on those threads, a > post-merge hook is a 1 line config change...but now you are left with dev > community that learns about changes post-facto, rather than being involved > in them. > I'm against this idea. As said you can already get involved if you care about documentation. I'm not sure if *every* dev is allowed to merge things into devmanual anyway, since it's a subproject of QA and has even its own dedicated project setup. https://wiki.gentoo.org/wiki/Project:Devmanual So who gets to decide what goes in and what not? Sure you can get more opinions if you post patches to mailing lists, but even now we've seen people hop in and review stuff they have no idea about. In the end I feel like the devmanual project has the final say, and should choose whether they want to get involved in mailing lists. It could get messy with reviews too, one party reviewing in GH, some reviewing in mailing lists... these opinions could conflict. With the "monthly devmanual updates" mail I believe it raises awareness enough and you could even advertise how one can get involved if they wish. I mean, in the end, I believe less than 5 % of our devbase actually care about any of this. And for someone wondering: you can watch the Github gentoo/devmanual repo to get notified when a PR is opened, and you can watch/add yourself to devmanual@g.o mail to get bugzilla notifications.
I am against this, because it is the wrong way around. The Devmanual should only see updates on which consensus has been reached. Obviously this must take place before committing. Also, do we really see commits like the following (picked at random, but all from this year) on the -dev mailing list? https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=ece9a5736c0a04daa7d03738a9b2624f088f85fa https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=20a8ffa9fdd1b9f30fd99346dc6c9f876a4af5f0 https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=ee1ca6dd07a2561d26029f4f0c1a5ef65160337e https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=a93ddfdf28dd37d25e4967c8c97b5bc93be70d15 People interesting in that kind of information can read (and filter) the gentoo-commits mailing list.
(In reply to Ulrich Müller from comment #5) > I am against this, because it is the wrong way around. The Devmanual should > only see updates on which consensus has been reached. Obviously this must > take place before committing. > Can you suggest an alternative then? juippis has given a constructive alternative (a monthly round-up) which we could do with a cronjob easily. Consensus being reached on an issue doesn't mean everyone on the gentoo-dev ML knows about it, plus it's still useful to see full explanatory text on an issue on top of what the general consensus is on how to handle something. This has been raised quite a few times to me about not knowing when devmanual or QA policy changes. > Also, do we really see commits like the following (picked at random, but all > from this year) on the -dev mailing list? > https://gitweb.gentoo.org/proj/devmanual.git/commit/ > ?id=ece9a5736c0a04daa7d03738a9b2624f088f85fa > https://gitweb.gentoo.org/proj/devmanual.git/commit/ > ?id=20a8ffa9fdd1b9f30fd99346dc6c9f876a4af5f0 > https://gitweb.gentoo.org/proj/devmanual.git/commit/ > ?id=ee1ca6dd07a2561d26029f4f0c1a5ef65160337e > https://gitweb.gentoo.org/proj/devmanual.git/commit/ > ?id=a93ddfdf28dd37d25e4967c8c97b5bc93be70d15 > > People interesting in that kind of information can read (and filter) the > gentoo-commits mailing list. Sure. Then let's talk about alternatives.
(In reply to Sam James from comment #6) I think there are four types of commits (maybe more): 1. Real policy changes: These should be discussed up front, and there should be consensus on mailing lists. Also monthly summary, if we decide that we should have something like that. 2. Documenting existing best practice: These could go to a monthly summary. 3. Bug fixes, small changes of wording, formatting fixes, refactoring: These need not be discussed widely, but can be handled internally by the devmanual team. I see no reason why these should appear in a monthly summary. 4. Technical things, like updating the build system, XSL and CSS stylesheets: Same as before. So no, IMHO we should not just blindly post the output of "git log --oneline --since=1month" to -dev, because that would contain too much noise. (Maybe it could still be done in some automatic, e.g. by using a special tag in the commit message?)
(In reply to Ulrich Müller from comment #7) > (In reply to Sam James from comment #6) > > I think there are four types of commits (maybe more): > 1. Real policy changes: These should be discussed up front, and there should > be consensus on mailing lists. Also monthly summary, if we decide that we > should have something like that. > 2. Documenting existing best practice: These could go to a monthly summary. > 3. Bug fixes, small changes of wording, formatting fixes, refactoring: These > need not be discussed widely, but can be handled internally by the devmanual > team. I see no reason why these should appear in a monthly summary. > 4. Technical things, like updating the build system, XSL and CSS > stylesheets: Same as before. > > So no, IMHO we should not just blindly post the output of "git log --oneline > --since=1month" to -dev, because that would contain too much noise. (Maybe > it could still be done in some automatic, e.g. by using a special tag in the > commit message?) ~/gentoo/devmanual $ git log --since 1month --oneline 876646b keywording: it's preferred to rekeyword packages with new deps e203df7 general-concepts/projects: mention IRC channels 70113f2 general-concepts/projects: consult project lead on joining 6756801 general-concepts/autotools: Remove comment re einfo e36a054 ebuild-writing/eapi: update link to Python guide 9db2bfb ebuild-writing/eapi: mention blocker retention period 57ba0f6 ebuild-writing/eapi: document upgrade path policy 3f0133a general-concepts/use-flags: give guidance on IUSE defaults 5ef9e1d general-concepts/dependencies: improve explaination of slot operators a4828a6 general-concepts/dependencies: indent xml for better raw readability f0be5cf archs/sparc: mention SIGBUS/unaligned access and link to tracker bug 17ea5e4 keywording: note that stabilization rules are for actual testing 5e91e85 general-concepts/portage-cache: add "metadata invariance" term 35b8e9e ebuild-maintenance/package-moves: link to updates/ page 1c2f5ca ebuild-writing/variables: link to package/slot move page in SLOT ece9a57 appendices/devbook-guide: Indent the table properly 9d82f20 ebuild-writing/variables: Whitespace aec6c83 ebuild-writing/variables: Selectively lifting SRC_URI restrictions I see a couple commits here that are obviously more noise than not, sure. Is avoiding these few lines of noise really worth this extra work of somehow categorizing every commit to devmanual.git? Especially when considering how much traffic gentoo-dev normally gets, worrying this much about a few lines of extra infromation is surely not worth the effort.
Yeah and it introduces a "human factor" which is faulty ;) Overall the devmanual git activity isn't that high that I'd consider these manual workarounds worth the effort... Sure there has been a couple months lately with increased activity, but on average there's ~10 commits per month?
(In reply to Joonas Niilola from comment #9) > Yeah and it introduces a "human factor" which is faulty ;) That makes no sense. It won't be perfect, but it would always be better than spamming the mailing list with an unfiltered list of all commits.
(In reply to Ulrich Müller from comment #10) > (In reply to Joonas Niilola from comment #9) > > Yeah and it introduces a "human factor" which is faulty ;) > > That makes no sense. It won't be perfect, but it would always be better than > spamming the mailing list with an unfiltered list of all commits. May be a difference in views, but 1 mail monthly with either 10 or 13 lines hardly counts as spam ;) Anyway how do you plan to construct your system? A footer-tag in a commit? Do you plan to oversee each commit made to devmanual weighing what's worthy of a footer tag and what's not? What about commits that go past you? Yeah it's not perfect. I can just imagine it's way more work than those extra 3 lines per month, and needs an additional "supervisor". In the end, will it be worth it?
(In reply to Joonas Niilola from comment #11) > (In reply to Ulrich Müller from comment #10) > > (In reply to Joonas Niilola from comment #9) > > > Yeah and it introduces a "human factor" which is faulty ;) > > > > That makes no sense. It won't be perfect, but it would always be better than > > spamming the mailing list with an unfiltered list of all commits. > > May be a difference in views, but 1 mail monthly with either 10 or 13 lines > hardly counts as spam ;) > > Anyway how do you plan to construct your system? A footer-tag in a commit? > Do you plan to oversee each commit made to devmanual weighing what's worthy > of a footer tag and what's not? What about commits that go past you? > > Yeah it's not perfect. I can just imagine it's way more work than those > extra 3 lines per month, and needs an additional "supervisor". In the end, > will it be worth it? Really just seems like we should go with the monthly deal and revisit if it's a problem. I don't anticipate it being one. Like you said, I don't think it's worth the work to "curate" the commits.. let's just try make people more informed and can re-evaluate in a bit if needed.
(In reply to Ulrich Müller from comment #5) > I am against this, because it is the wrong way around. The Devmanual should > only see updates on which consensus has been reached. Obviously this must > take place before committing. I think you have entirely missed the point and as a result left some nonproductive and frankly abrasive comments on this bug. Let me try to explain the purpose. Multiple times in recent years we've had low-activity developers complain that they were not aware of X, Y, or Z. They've asked that there be some sort of refresher page in the devmanual, for example. juippis did this in https://github.com/gentoo/devmanual/pull/235 but you have effectively blocked it from landing. In my thread on gentoo-dev@ about deprecating repoman, a developer complained that "our developer documentation needs to be updated to reference the new tool and the new way of doing things" and "Right now, that documentation is going to more or less tell me to stick with repoman.". It is apparent that despite Sam having updated the devmanual a year ago to describe pkgdev, that this developer is still not aware of it. It's not clear to me why he would be, as Sam says in comment #1: > This came up earlier in #gentoo-dev when discussing the repoman/pkgcheck migration, but it's been on my mind anyway as a method to keep folks informed. > > "We updated the devmanual, it's been there for a while" etc isn't a very helpful comment because I don't think developers are really going to be re-reading every page weekly or monthly or something. So, please try to understand the purpose and work with us to find a solution.
(In reply to Matt Turner from comment #13) > I think you have entirely missed the point and as a result left some > nonproductive and frankly abrasive comments on this bug. So far this was a factual discussion. Now you attack me in person, completely unprovoked? End of discussion for me.
(In reply to Ulrich Müller from comment #14) > (In reply to Matt Turner from comment #13) > > I think you have entirely missed the point and as a result left some > > nonproductive and frankly abrasive comments on this bug. > > So far this was a factual discussion. Now you attack me in person, > completely unprovoked? > > End of discussion for me. I'm sorry that my comment was interpreted that way. It's not at all my goal to attack you. My goal is to have you take a step back and understand the purpose of the proposal and to at least acknowledge the benefits before you criticize each detail in depth. I found this article to be very insightful, and I hope you'll take the time to read it: https://blog.the-pans.com/wrong/ The reason I posted my comment was precisely because I value your opinions. I want to hear them, but I don't think the method in which you've giving them is productive or leading towards a satisfactory resolution to the problem at hand. If you really feel that I've personally attacked you, please contact ComRel (of which I'm a member--I'd of course not be involved). I welcome feedback on my communication, so I would gladly accept constructive criticism.
The following results from a discussion with sam and dilfridge in IRC; maybe this could be used as further input: - Only include commits in the summary that modify at least one *.xml file (so no changes that affect only build system, stylesheet etc.). - Further refine by a commit message tag (e.g. "Filter: trivial", details to be discussed), as I had previously suggested in the last paragraph of comment #7. Both should be easy to implement with git log, by specifying '*.xml' as path and using the --grep option for the commit message. (In reply to Matt Turner from comment #15) Thanks for the clarification.
