<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">Le mar. 7 janv. 2020 à 04:36, Nyall Dawson <<a href="mailto:nyall.dawson@gmail.com">nyall.dawson@gmail.com</a>> a écrit :<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On Tue, 7 Jan 2020 at 11:59, DelazJ <<a href="mailto:delazj@gmail.com" target="_blank">delazj@gmail.com</a>> wrote:<br>
><br>
> Hi all,<br>
><br>
> Thanks Denis for the work.<br>
> 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:<br>
><br>
> 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.<br>
><br>
> 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.<br>
> 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...<br>
><br>
> 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.<br>
> 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?<br>
><br>
> 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.<br>
> 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?<br>
<br>
I guess I'm most excited about the future possibilities here ;) I love<br>
that new message which the PR submitter gets pinged on to direct their<br>
attention to the new documentation ticket, and the not-so-subtle<br>
request it makes for them to aid with their feature's documentation.<br>
I'm sure we'd all agree that the more we can encourage/force the<br>
original developers to work WITH the documentation team the better the<br>
whole system will work for everyone. I really like that anyone can go<br>
and add the label to someone else's PR without having to nag/remind<br>
them to add the message to their commits.<br>
<br>
I was also under the impression that the whole PR description would<br>
also be lifted across to the new documentation issue, and I can<br>
clearly see that the new text is a regression in terms of making a<br>
readable ticket.<br>
<br>
My "ideal" setup would looks something like what we have now, but with:<br>
<br>
- copy the whole PR message and images across to the new ticket<br>
- also copy the content of any [needs-docs] tagged commits from the PR<br>
- have a modified version of the stale bot running on the<br>
documentation issues queue, which keeps hassling the PR submitter<br>
every xx weeks until the corresponding documentation ticket is closed.<br>
("Hey, you still haven't added the required documentation for your<br>
.... feature. This isn't playing nice with the QGIS community --<br>
please rectify this ASAP!")<br></blockquote><div><br></div><div>So this would mean setting the author of the PR as assignee of the issue on the doc repo?</div><div>And then a stale bot on this?</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
- (my personal #1) as well as opening the documentation ticket, we<br>
also automatically populate the changelog with the text and images<br>
from the PR description.</blockquote><div><br></div><div>It shouldn't be a big deal I guess.</div><div>I believe there is already a bot which does something for [FEATURE] commits right?</div><div>This is out of scope, but depending on time left I could potentially do it. </div><div><br></div><div>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).</div><div><br></div><div>Denis</div></div></div>