[arch-dev-public] New ideas for notifying users about (minor) changes
Hello everybody, I got assigned to this issue here:
https://bugs.archlinux.org/task/62823
The users would like to have a notice in pre/post install/upgrade notifications via pacman .install files.
I am not a fan of spamming such news via pacman and I think the installation/upgrade process should be clean of such messages, but I don't have access to the news tool on our website as well.
So what can we do here? I am a big fan of Gentoos Newsletter feature[1]. It would be super awesome if we would have a tool such like `archnews <packagename>` to retrieve NEWS about a certain package from an endpoint. This endpoint should be controllable by every maintainer (devs and TUs included). I discussed this with coderobe a bit and we came to different solutions:
Solution 1: a NEWS file inside of the package repository: --------------------------------------------------------
A maintainer could upload a `NEWS` file into the package repository and then a client could grab this information directly via downloading the file from:
https://git.archlinux.org/svntogit/community.git/plain/trunk/NEWS?h=packages...
Pro: + every maintainer could control this NEWS file easily via our current tools. + It's easy to download the NEWS files (we can expect new tools from the community)
Con: - We bloat our repository
Solution 2: commit messages as NEWS ------------------------------------
The maintainer could/should put such news into the latest commit message.
Pro: + no extra file + using existing infrastructure + one workflow
Con: - I need an actual change in the repository to create a new NEWS object (If we have a look on my example with strongswan, I would need to add something in the PKGBUILD to make a new commit to make a new NEWS object) - It's more difficult to get with tools. The user needs to checkout the repository (in solution 1 it can be just a curl call)
Solution 3: A webapp on news.archlinux.org with a fancy UI -----------------------------------------------------------
This solution would be the most work. We could have a new webapp (such like our security tracker) just for NEWS objects. Every maintainer should have access to their assigned packages.
Pro: + Fancy + Easy to use + API endpoints
Con: - A lot of work -------------------------------------------------------------
I would go for solution 1. What would be interesting to know for me:
1. Do you think that we actually *need* such a tool? 2. Would you use such a tool/workflow? 3. Do you have other/better ideas?
I hope for an interesting constructive discussion.
Best regards
chris
[1] https://wiki.gentoo.org/wiki/Gentoo_Cheat_Sheet#Gentoo_Monthly_Newsletter_.2...
On 7/29/19 6:47 PM, Christian Rebischke via arch-dev-public wrote:
Hello everybody, I got assigned to this issue here:
https://bugs.archlinux.org/task/62823
The users would like to have a notice in pre/post install/upgrade notifications via pacman .install files.
I am not a fan of spamming such news via pacman and I think the installation/upgrade process should be clean of such messages, but I don't have access to the news tool on our website as well.
It's not unreasonable to add such post_upgrade messages in cases where you want to ensure the user sees the message.
So what can we do here? I am a big fan of Gentoos Newsletter feature[1]. It would be super awesome if we would have a tool such like `archnews <packagename>` to retrieve NEWS about a certain package from an endpoint. This endpoint should be controllable by every maintainer (devs and TUs included). I discussed this with coderobe a bit and we came to different solutions:
Solution 1: a NEWS file inside of the package repository:
A maintainer could upload a `NEWS` file into the package repository and then a client could grab this information directly via downloading the file from:
https://git.archlinux.org/svntogit/community.git/plain/trunk/NEWS?h=packages...
Pro:
- every maintainer could control this NEWS file easily via our current
tools.
- It's easy to download the NEWS files (we can expect new tools from the
community)
Con:
- We bloat our repository
We already have this feature.
Add the following to the PKGBUILD, and rebuild it:
changelog=NEWS
Now, the user may at any time run the following command for an installed package:
$ pacman -Qc pkgname Changelog for pkgname: [contents of NEWS file]
Changelogs are pacman's #1 unused feature. Do note, however, that these messages are opt-in and thus users won't see them unless they know they need to. As such, it makes sense for a "changelog", but its utility as a news bulletin may be in doubt.
Solution 2: commit messages as NEWS
The maintainer could/should put such news into the latest commit message.
Pro:
- no extra file
- using existing infrastructure
- one workflow
Con:
- I need an actual change in the repository to create a new NEWS object (If we have a look on my example with strongswan, I would need to add something in the PKGBUILD to make a new commit to make a new NEWS object)
- It's more difficult to get with tools. The user needs to checkout the repository (in solution 1 it can be just a curl call)
People should already use decent commit messages. But we should *not* abuse them to contain information that is not about what the commit did, but instead about how users should respond to the new package release.
That duplicates the functionality of a changelog without offering a compelling use case that it would be better at. It additionally makes commit messages *worse* at effectively doing the job of a commit message.
Solution 3: A webapp on news.archlinux.org with a fancy UI
This solution would be the most work. We could have a new webapp (such like our security tracker) just for NEWS objects. Every maintainer should have access to their assigned packages.
Pro:
- Fancy
- Easy to use
- API endpoints
Con:
- A lot of work
That duplicates the functionality of a changelog without offering a compelling use case that it would be better at. The only thing that would be possible with this, that a changelog cannot do, is tell you about the news for a package you don't have installed, but I assume you don't actually care about that.
I would go for solution 1. What would be interesting to know for me:
- Do you think that we actually *need* such a tool?
- Would you use such a tool/workflow?
- Do you have other/better ideas?
I do not thing we need such a tool, and if we had one, I would refuse to use it -- instead opting to use the changelog feature.
I would still use post_upgrade messages that use vercmp to make sure they run exactly once, to alert users to important issues surrounding a new release that I do not want them to accidentally miss.
See community/sigil for an example of using post_upgrade for warnings that I want all users to see.
See community/fanficfare for an example of using changelogs to make the list of changes in the package, more accessible.
Con:
- We bloat our repository
We already have this feature.
Add the following to the PKGBUILD, and rebuild it:
changelog=NEWS
Now, the user may at any time run the following command for an installed package:
$ pacman -Qc pkgname Changelog for pkgname: [contents of NEWS file]
Changelogs are pacman's #1 unused feature. Do note, however, that these messages are opt-in and thus users won't see them unless they know they need to. As such, it makes sense for a "changelog", but its utility as a news bulletin may be in doubt.
This was exactly my thought. If anything, we may want to push for maintainers to include NEWS files more often and possibly think about how to bring the changelog feature to the forefront.
Cheers! -Santiago.
We already have this feature.
Add the following to the PKGBUILD, and rebuild it:
changelog=NEWS
Now, the user may at any time run the following command for an installed package:
$ pacman -Qc pkgname Changelog for pkgname: [contents of NEWS file]
Changelogs are pacman's #1 unused feature. Do note, however, that these messages are opt-in and thus users won't see them unless they know they need to. As such, it makes sense for a "changelog", but its utility as a news bulletin may be in doubt.
Ah ok cool. You didn't mention that `pacman -Qc` part when we talked about it in the IRC.
One problem what I see with `pacman -Qc` is that we would still need a wrapper for it, because I don't want to trigger `pacman -Qc` for every package on my machine manually (or with some bash magic.. I know it's a one liner).
And I guess it will always print the whole changelog, correct? The name changelog is irritating as well, atleast I wouldn't expect minor news in there.
People should already use decent commit messages. But we should *not* abuse them to contain information that is not about what the commit did, but instead about how users should respond to the new package release.
That duplicates the functionality of a changelog without offering a compelling use case that it would be better at. It additionally makes commit messages *worse* at effectively doing the job of a commit message.
Good points. Another question: How can we enforce better commit messages? This could be a nice question for the next Arch Linux Meetup, to discuss.
That duplicates the functionality of a changelog without offering a compelling use case that it would be better at. The only thing that would be possible with this, that a changelog cannot do, is tell you about the news for a package you don't have installed, but I assume you don't actually care about that.
Yep, I think so as well.
I do not thing we need such a tool, and if we had one, I would refuse to use it -- instead opting to use the changelog feature.
I would still use post_upgrade messages that use vercmp to make sure they run exactly once, to alert users to important issues surrounding a new release that I do not want them to accidentally miss.
My problem with post_upgrade messages is that it's difficult to differ between 'breaking notifications' and 'documentations'. If you have a look into the AUR you will see tons of packages that use the install files as installation documentation (this is exactly the opposite what I want). Furthermore if everybody would use such post_upgrade messages, we would get spammed with it.. If we use them rarely, they are fine, but for everything bigger they are the wrong solution, imho.
On Mon, 29 Jul 2019 at 18:47:44, Christian Rebischke via arch-dev-public wrote:
So what can we do here? I am a big fan of Gentoos Newsletter feature[1]. It would be super awesome if we would have a tool such like `archnews <packagename>` to retrieve NEWS about a certain package from an endpoint. This endpoint should be controllable by every maintainer (devs and TUs included). I discussed this with coderobe a bit and we came to different solutions:
Solution 1: a NEWS file inside of the package repository:
[...] Solution 2: commit messages as NEWS
[...] Solution 3: A webapp on news.archlinux.org with a fancy UI
If we decide to do this, why don't we simply add a file to the package? It's simple, works offline, and always gives you the right version of the news for your system.
On Mon, Jul 29, 2019 at 07:36:31PM -0400, Public mailing list for Arch Linux development wrote:
On Mon, 29 Jul 2019 at 18:47:44, Christian Rebischke via arch-dev-public wrote:
So what can we do here? I am a big fan of Gentoos Newsletter feature[1]. It would be super awesome if we would have a tool such like `archnews <packagename>` to retrieve NEWS about a certain package from an endpoint. This endpoint should be controllable by every maintainer (devs and TUs included). I discussed this with coderobe a bit and we came to different solutions:
Solution 1: a NEWS file inside of the package repository:
[...] Solution 2: commit messages as NEWS
[...] Solution 3: A webapp on news.archlinux.org with a fancy UI
If we decide to do this, why don't we simply add a file to the package? It's simple, works offline, and always gives you the right version of the news for your system.
good point, I guess this would be solution number 4.
On 30/7/19 8:47 am, Christian Rebischke via arch-dev-public wrote:
Hello everybody, I got assigned to this issue here:
https://bugs.archlinux.org/task/62823
The users would like to have a notice in pre/post install/upgrade notifications via pacman .install files.
I am not a fan of spamming such news via pacman and I think the installation/upgrade process should be clean of such messages, but I don't have access to the news tool on our website as well.
I think this is a clear case of user intervention needed. So a post_install message (restricted to the update where intervention was needed) is appropriate.
If the package was more widely used, we have the News section of the website.
I don't think anything else is needed.
Allan
On Tue, Jul 30, 2019 at 10:16:17AM +1000, Allan McRae wrote:
On 30/7/19 8:47 am, Christian Rebischke via arch-dev-public wrote:
Hello everybody, I got assigned to this issue here:
https://bugs.archlinux.org/task/62823
The users would like to have a notice in pre/post install/upgrade notifications via pacman .install files.
I am not a fan of spamming such news via pacman and I think the installation/upgrade process should be clean of such messages, but I don't have access to the news tool on our website as well.
I think this is a clear case of user intervention needed. So a post_install message (restricted to the update where intervention was needed) is appropriate.
If the package was more widely used, we have the News section of the website.
I don't think anything else is needed.
Allan
One problem I see with the News section is that it's Dev only. I wouldn't even know who I need to ask (and I am TU for several years now). I mean I could just ask around in the IRC, but it would be nice to have this at least documented somewhere. Another question is how fast this will happen.. you will always have a delay if you need to forward the message to another person first before publishing it.
I guess I will stick with post_upgrade messages for strongswan, thanks. And I will definitely have a look at this changelog feature (either as news replacement or for providing the actual changelog of the software).
On 30/7/19 10:44 am, Christian Rebischke wrote:
One problem I see with the News section is that it's Dev only. I wouldn't even know who I need to ask (and I am TU for several years now). I mean I could just ask around in the IRC, but it would be nice to have this at least documented somewhere.
I guess the assumption is changes that affect a larger proportion of users are in packages maintained by devs. However, I'm happy opening the news to TUs if needed.
Allan
On 30/07/2019 02.44, Christian Rebischke via arch-dev-public wrote:
One problem I see with the News section is that it's Dev only. I wouldn't even know who I need to ask (and I am TU for several years now).
The list of developers is public. If after few years you don't know a single person to ask if they could proofread and publish something for you, or even can't send a draft yourself to arch-dev-public, introducing another tool won't help at all.
BP
On 30/07/2019 09.33, Bartłomiej Piotrowski via arch-dev-public wrote:
On 30/07/2019 02.44, Christian Rebischke via arch-dev-public wrote:
One problem I see with the News section is that it's Dev only. I wouldn't even know who I need to ask (and I am TU for several years now).
The list of developers is public. If after few years you don't know a single person to ask if they could proofread and publish something for you, or even can't send a draft yourself to arch-dev-public, introducing another tool won't help at all.
BP
I have also changed TU permissions to include "add news" and "change news" actions.
participants (6)
-
Allan McRae
-
Bartłomiej Piotrowski
-
Christian Rebischke
-
Eli Schwartz
-
Lukas Fleischer
-
Santiago Torres-Arias