[Qgis-psc] [QGIS-Developer] Documentation bot

[Denis Rouzaud]

Le mar. 7 janv. 2020 à 04:36, Nyall Dawson <nyall.dawson at gmail.com> a
écrit :

> On Tue, 7 Jan 2020 at 11:59, DelazJ <delazj at gmail.com> wrote:
> >
> > Hi all,
> >
> > Thanks Denis for the work.
> > I might be missing some key points because comparing the generated
> reports from the two systems, I'm sorry I feel like it's instead a
> regression. Alow me to explain:
> >
> > 1. For the same feature merged in the code, see old system report [0] vs
> new system's [1]. From a doc writer perspective, I get more information
> from the first one than the second.
> >
> > 2. Another point is that milestone is what we use to filter issues
> reports and manage the docs schedule, so if it's not set by the developer
> (assuming that the dev knows the milestone to indicate), someone has to do
> it manually in the generated report. With the current system, when we enter
> a new development cycle, we (Richard and myself) set the new milestone (for
> LTR) and the target version label [2] and then, every generated report is
> automatically filled with these information at their creation. Done once
> and nobody cares about anymore. Until the next release.
> > This new system means devs "should" enter that information for each
> doc-related PR. I can't count the number of times I made a remind for the
> [needs-docs] label, and the PR was merged without...
> >
> > 3. What is meant by "developers should take care of it"? When/where will
> the details of the feature be available? If the dev wants to write about
> his changes in our docs, OK. Otherwise, are we not overloading their
> workload while they could have provided the necessary bits in the commit
> message, as they should be doing currently.
> > What I understood from the proposal is that developers will be
> encouraged to detail their feature in the PR message, the place they sell
> their feature to others, using a simple and accessible language. And then,
> at the merge time, the message of the PR (with maybe screenshots) will be
> copied to the generated report in docs, allowing writers to see what the
> feature is. Did I misunderstand or have the options changed meanwhile?
> >
> > Sorry if I'm less joyful than others (I'm not comfortable to comment a
> work I could not be able to do, and in English - so sorry if some
> words/tone seem used inappropriately) but from a doc repository manager
> pov, I'm envisioning more work and less information than we wished. For
> both writers and devs. and I wish I'm wrong.
> > For developers, what does it make easier to you? Nyall, I find your
> features very easy and pleasant to document given that  doc related changes
> are clearly separated and fully described for writers (see eg [3] which
> generate [4][5][6] ) so I'm a bit lost reading your comment above. What
> would this improve for you? Btw I wonder what/how this PR in [3] would have
> generated as issue report(s) in the doc repository with the new system?
>
> I guess I'm most excited about the future possibilities here ;) I love
> that new message which the PR submitter gets pinged on to direct their
> attention to the new documentation ticket, and the not-so-subtle
> request it makes for them to aid with their feature's documentation.
> I'm sure we'd all agree that the more we can encourage/force the
> original developers to work WITH the documentation team the better the
> whole system will work for everyone. I really like that anyone can go
> and add the label to someone else's PR without having to nag/remind
> them to add the message to their commits.
>
> I was also under the impression that the whole PR description would
> also be lifted across to the new documentation issue, and I can
> clearly see that the new text is a regression in terms of making a
> readable ticket.
>
> My "ideal" setup would looks something like what we have now, but with:
>
> - copy the whole PR message and images across to the new ticket
> - also copy the content of any [needs-docs] tagged commits from the PR
> - have a modified version of the stale bot running on the
> documentation issues queue, which keeps hassling the PR submitter
> every xx weeks until the corresponding documentation ticket is closed.
> ("Hey, you still haven't added the required documentation for your
> .... feature. This isn't playing nice with the QGIS community --
> please rectify this ASAP!")
>

So this would mean setting the author of the PR as assignee of the issue on
the doc repo?
And then a stale bot on this?


> - (my personal #1) as well as opening the documentation ticket, we
> also automatically populate the changelog with the text and images
> from the PR description.


It shouldn't be a big deal I guess.
I believe there is already a bot which does something for [FEATURE] commits
right?
This is out of scope, but depending on time left I could potentially do it.

Another thing we could do is writing a message as soon as the PR gets the
tag "Nees Documentation" to tell the author to update the description (and
not wait for it to be merged).

Denis
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-psc/attachments/20200107/f0777bb0/attachment.html>