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

[Denis Rouzaud]

Hi all,

I just realized this mail wasn't sent publicly. Here is a follow up on the
documentation bot.


Le ven. 10 janv. 2020 à 16:42, Denis Rouzaud <denis.rouzaud at gmail.com> a
écrit :

> Hi all,
>
> Here is a quick follow-up:
>
> * When the PR is created or labeled as Needs Documentation, a comment is
> left to tell the author what he should/could do
> see the message
> https://github.com/qgis/QGIS/pull/33638#issuecomment-571864199
>
> * When the PR is merged, its content is now copied to the doc issue (PR
> body + messages from commits tagged with needs-doc or FEATURE.
> see the created doc issue
> https://github.com/qgis/QGIS-Documentation/issues/4763
>
> * Regarding milestones, it was awfully tricky since admin rights are
> required to create and set milestones and our bot has its key public.
> What I did in the end, is a scheduled (cron) github action which sets the
> milestones of the PR based on the branch they are targeting.
> This is done here:
> https://github.com/qgis/QGIS/blob/master/.github/workflows/pr-auto-milestone.yml
> So except if the PR is merged before the cron job has run (chances are
> low, except for hard pushers ;) ), the label should be correctly set at the
> end!
>
> I hope it better suits the needs. Let's see how it works :)
>
> And sorry for the noisy spammy notifications you got last days. I tried to
> work on other repos (almost) as much as I could do.
>
> Denis
>
>
> Le mar. 7 janv. 2020 à 11:25, DelazJ <delazj at gmail.com> a écrit :
>
>> Hi Matthias
>>
>> Le mar. 7 janv. 2020 à 09:14, Matthias Kuhn <matthias at opengis.ch> a
>> écrit :
>>
>>> Hi
>>>
>>> Thanks a lot for this Denis. Having the technical base system for this
>>> set up is a good step forward!
>>>
>>> The biggest advantage of this itself is the direct *link from the
>>> documentation issue to the pull request* (instead of a commit message
>>> as previously).
>>>
>> One click saved. but I agree, the route to the PR is not always obvious
>> to everyone, particularly if we want to attract beginners.
>>
>>> I think instead of trying to push the developer to directly work on the
>>> documentation (which is something that not everyone in the documentation
>>> team is stoked about either) is to push them towards writing a nice pull
>>> request message which - in the best case - can be copied (and rst'ified) by
>>> someone from the documentation team. In the worst case it needs rewriting
>>> but at least the documentation team has a place (the pull request) to
>>> hassle the dev for more information.
>>>
>> Please Matthias, no, not you. You are among the devs regularly
>> writing/answering to docs in recent years. Do you really think there are
>> people in the docs team that are against developers working on the
>> documentation repository?
>>
>>>
>>> My proposals for the two comments are something like
>>>
>>> Pull request (after merge):
>>>
>>> > Because this pull request has been tagged as needs documentation, a
>>> new [issue has been opened](linktoissue). Please make sure that the
>>> documentation team has enough information by updating the description of
>>> this pull request with readable and understandable content, supported by
>>> images and screenshots where appropriate. Thank you for making documenting
>>> this as easy as possible and for working with the documentation team.
>>>
>>>
>>> Issue (on docs side):
>>>
>>> > A [pull request which requires documentation](linktopr) has been
>>> merged. Refer to the description in the pull request. If you have open
>>> questions, do not hesitate to ask them to @author-of-pr.
>>>
>>>
>>> The original description can be copied to the doc issue or not, I'm not
>>> sure what's better (keeping it only in the PR has the advantage that it's
>>> in a single place and if modified after merge we don't have two different
>>> copies).
>>>
>>>
>>> I'm OK with both suggestions and I think that keeping all the necessary
>> information at a single place could be better (I mentioned the copy because
>> this is what I had in mind regarding the grant discussion).
>>
>>> About the target version / milestones. If Richard and Harissou already
>>> up to now kept a mapping of master -> milestone up to date, we could
>>> consider to keep this going. Having a simple mapping of "target branch" to
>>> "doc milestone" (e.g. master -> 3.12, release-3_10 -> 3.10, ...) somewhere
>>> sounds not too convoluted. Or maybe Jürgens release scripts could do that
>>> even in an automated way.
>>>
>>>
>>> Anything that ensures the information is filled automatically is good to
>> me.
>>
>>> In the end, this process has to work for the documentation team, please
>>> take these ideas with a grain of salt. In my opinion we want to have 1) a
>>> good draft by the dev and 2) a communication channel for documentors. Let
>>> us know what works best for you, documentation team and to what degree you
>>> want devs to be involved with actual writing.
>>>
>> I personally share your desire. I've complained about the lack of bridges
>> between developers and writers so I'm not going to spit on efforts that
>> would improve the situation...
>> About the degree of involvement of developers in actual writing, as long
>> as I know, QGIS is a community driven project. Meaning that if I want, I
>> can contribute to code, to docs, to website, to discussion, to
>> everything... Why would there be a restriction for some people because they
>> are "tagged" developers? I think everyone should be allowed to submit the
>> changes he feels is improving the documentation, either through PRs to
>> docs, description to code PRs or answering questions... As I said earlier,
>> if the developers feels comfortable in writing about their changes, please
>> do. The only thing is that the same way there are rules in contributing to
>> QGIS repo, there are some in QGIS-Documentation and we need to deal with
>> them. But why should these be a barrier to not write?
>> That said, I'm *not* the documentation team (*what is the documentation
>> team actually?*) and it seems there are various opinions on this topic
>> so let's hear others.
>>
>> Hope this helps and best regards
>>>
>> It does.
>>
>> Regards,
>> Harrissou
>>
>>> Matthias
>>> _______________________________________________
>>> QGIS-Developer mailing list
>>> QGIS-Developer at lists.osgeo.org
>>> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
>>> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer
>>
>> _______________________________________________
>> QGIS-Developer mailing list
>> QGIS-Developer at lists.osgeo.org
>> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
>> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20200118/b5e7bbaa/attachment.html>