Embedded end-user feedback

[Guts]

QGIS Enhancement: end-user feedback and workflow

Date 2024/03/212
Author Julien Moura (@Guts) and Julien Cabièces (@troopa81)
Contact julien.moura@oslandia.com
Version QGIS 3.40

Summary

Reporting bugs and other feature requests is quite difficult for average QGIS end-users, who are more geomatics than IT oriented.
As GitHub's interface is not internationalized and oriented towards developer collaboration, there is a challenge in enabling end-users to interact more easily with the developer community.

This QEP proposes to ship a feedback form/widgets as a QGIS in-app tool in order to improve the way we gather end-user feedback.

Functionally, this would take the form of a reporting form fully integrated in Qt, with input fields corresponding to the issue forms

Features envisaged :

• localized form with an extensive helping text
• authenticated using the a Github token with a wizard to help end-user create one
• choice of ticket type (bug or feature request). It may be necessary to make the existing template issue evolve in order to make it consistent with the embedded form: specific labels, specific fields, etc.
• embedded markdown editor with preview
• a button to easily create a new debug profile where to try to reproduce
• automatic integration of debug information (About menu, log messages, plugins list, etc). Ideally, the end-user can check/uncheck which information is sent (SQL logs, networks logs...).
• think a way to obfuscate potential sensible information logs
• lookup in existing Github issues (through API calls)
• mandatory commitment to devote time to following up the ticket
• attach some extra data: images, zip, logs... everything which is compatible with Github form
• allow user store consistent informations to reuse accross different reports and avoid him to rewrite evertytime the same thing
• notify the end-user directly in QGIS if an answer has been posted in one of his issues, by polling/websocket the github API (twice a day, opt-in feature) and displaying a message bar with a button redirecting to the web browser

To give an idea, here is a quick and dirty form:

QGIS currently includes a crash management mechanism (called crash handler) that generates pre-filled issues with information about the environment. The aim is to reuse the existing code and extend it to handle more use cases.

Example(s) and inspirations

There is already some plugins that implement a report workflow for the plugins ecosystem:

• https://github.com/lutraconsulting/qgis-report-plugin
• https://github.com/wonder-sk/qgis-first-aid-plugin

Affected Files

• file where the github token is managed in QGIS settings (console_settings.py --> feature "share on gist") --> rewrite into Qt

Votes

(required)

[anitagraser]

Thank you for submitting your proposal to the 2024 QGIS Grant Programme. The 2 week discussion period starts today. At the end of the discussion, the proposal author has to provide a 3-line pitch of their proposal for the voter information material. (For an example from last year check qgis/PSC#58 (comment))

[haubourg]

Reporting bugs and other feature requests is quite difficult for average QGIS end-users, who are more geomatics than IT oriented.
As GitHub's interface is not internationalized and oriented towards developer collaboration, there is a challenge in enabling end-users to interact more easily with the developer community.

This QEP proposes to ship a feedback form/widgets as a QGIS in-app tool in order to improve the way we gather end-user feedback.

I totally agree, raising an issue is still hard for non english and non tech users.
Being able to push issues from QGIS, and being able to keep the context is interesting too.

I've done this in a corporate environnement, where users could just push a simple issue descriptions, and we kept a screenshot and all technical context under the hood.

However, I feel like this can be something not totally sustainable. Here is why :

• In my organization, this tool was not used much, even with a lot of training and human proximity. I'm not sure users afraid by Github are real contributors (speaking population wide)
• We create a hard dependency on Github API, which we don't manage. If it changes, QGIS feature will stop working.
• Users have to create a token, but they expire at least yearly. How to help them renew them?
• We will have more issues, which is good, but maybe harder to triage and manage. And we will have more non english issues, reducing the pool of possible triagers.
• We don't educate users to go themselves learn GitHub, so the load of adaptating to Github's changes will be on our shoulders.
• Our current limiting factor is our ability to triage them. Increasing the input flow as we havent' adressed the **growing 4K opened issues ** problem, might be some bad gift to our already overwhelmed triager's team.
• We currently have 500K QGIS opening's a day. Polling he API for answers, similar issues etc, will probably lead to 5 - 30 API call per day. Everything with the same QGIS user agent. I'm afraid GitHub will start to at least identify us, and maybe block us. Which would lead to a broken core feature without any way to fix. That can be dealt by discussion with them.

I feel like the really issue is that Github is non-english unfriendly. In beta version, translation of comments is on its way. UI not yet
https://github.blog/changelog/2021-07-19-machine-translation-for-discussions-content/

It is already possible to auto translate interface, but it is ugly :
https://github-com.translate.goog/qgis/QGIS/issues?_x_tr_sl=auto&_x_tr_tl=fr&_x_tr_hl=fr

I'm don't think we can solve this by making a proxy of github on our side, this is too big to maintain in the long run.

And last point, when rewriting QGIS' website, PSC decided to not translate it. The workload for translator teams is too high and we bet that AI translation tools are solving the issue for us.
I know this will be an issue in France, but this has a massive cost, and we are at a point of history of having partial translations deserve the project.

However, pivoting this proposal to a generic plugin that organizations could parameterize to their internal git forge would be excellent, I dream of it. Then the GIS admin can extract its critical issues to QGIS upstream (and hopefully fund fixes) .

[nyalldawson]

I also have concerns about this leading to more non-English bug reports.

I just don't think we have the people power available to manage these effectively and ensure that the relevant information is accessible to developers with the ability to actually fix the bugs.

I don't know if it's just an idea in the mockup, but I'm also strongly against collecting the social handles of the users (ie the linked in / twitter details). I can't see any reason we'd want this or in which it would be valuable for us. (More broadly, I'm extremely against any sign of "official" QGIS endorsement/support to Twitter in any way, given the disgusting cesspool of intolerance and extremism that it's become under Musk's guidance).

Lastly, if the user has to sign up to Github and then go through the hassle of creating a token themselves, that seems to me to be much more complex then just signing up to Github and filing the issue directly 😆 . I realise it alleviates non-English use of Github, but creating a token is a scary/complex process for anyone completely new to Github regardless of how nicely we wrap it up in a wizard on QGIS' side... Maybe there's ways to avoid the user requiring their own key, eg through some custom service hosted on QGIS infrastructure which handles the actual GitHub API portion and issue filing using an internal hidden QGIS token?

[Guts]

Thanks for your interest and for taking time to write here @haubourg and @nyalldawson.

We create a hard dependency on Github API, which we don't manage. If it changes, QGIS feature will stop working.

I think there is some confusion here. To create the issue, no call to the Github API is necessary. It's just a URL with query parameters corresponding to the issue form. Click me to have an issue with prefilled fields.

About adherence to a platform (and a proprietary one!), the risk is not important here:

• issues are so intensively and widely used that Github is unlikely to break things suddenly
• if it happens (probability still > 0), the feedback form won't be the first concern I guess
• similar mechanisms exist in other forges (even in Gitea) so the change would be quite affordable

On the other hand, I find it more questionable that QGIS embeds a hard-coded dependency on the fonts.google.com service (in the fonts downloader), which is certainly handy but also serves as a tracker for the world's leading advertiser.

We don't educate users to go themselves learn GitHub, so the load of adaptating to Github's changes will be on our shoulders.

Is educating users to raise their Github skills a goal or even a mission for the QGIS project? I don't think so. Why not educate developers to learn using QGIS on Windows 11 for a mapping work expected for the next week? Just kidding obviously but in my opinion, this comment is emblematic of a developer's posture and how much the project can be more developer's centric, and we can look at things from another angle: why should a QGIS user learn to use a software forge, which is the developers' software?

I don't know if it's just an idea in the mockup, but I'm also strongly against collecting the social handles of the users (ie the linked in / twitter details). I can't see any reason we'd want this or in which it would be valuable for us. (More broadly, I'm extremely against any sign of "official" QGIS endorsement/support to Twitter in any way, given the disgusting cesspool of intolerance and extremism that it's become under Musk's guidance).

Sorry for that, I was in a hurry and wanted to give a graphical view of the idea and, as the dialog's title reveals it, I just quickly modify a form used in QTribu (Geotribu's plugin) where social accounts are used in the publication workflow. So, yes it's definitely just an idea. No worries and sorry for that.

[Guts]

Users have to create a token, but they expire at least yearly. How to help them renew them?

Lastly, if the user has to sign up to Github and then go through the hassle of creating a token themselves, that seems to me to be much more complex then just signing up to Github and filing the issue directly 😆 . I realise it alleviates non-English use of Github, but creating a token is a scary/complex process for anyone completely new to Github regardless of how nicely we wrap it up in a wizard on QGIS' side... Maybe there's ways to avoid the user requiring their own key, eg through some custom service hosted on QGIS infrastructure which handles the actual GitHub API portion and issue filing using an internal hidden QGIS token?

I have to digg more into the Github token management for 3rd party but I think we can declare QGIS as an identified application (like services a codecov, pre-commit.ci, git guardian, etc.) that can manage some tokens.

Not sure if hosting a middleware is required or not.

[Guts]

We will have more issues, which is good, but maybe harder to triage and manage. And we will have more non english issues, reducing the pool of possible triagers.
I also have concerns about this leading to more non-English bug reports.

Sorry my English isn't sharp enough I guess 😆 ! In my opinion, I don't think we should accept issues in languages other than English. I'm talking about translating the form: labels, buttons, placeholders, tooltips, help, and so on. We could also offer the user a button to translate the content of his issue on external services (deepl, google translate...), making the work easier for him.