[QGIS-Developer] [Qgis-psc] Updates to the way changelog entries are managed
Tim Sutton
tim at kartoza.com
Tue Jul 14 15:42:22 PDT 2020
Hi Harrissou
> On 10 Jul 2020, at 10:45, DelazJ <delazj at gmail.com> wrote:
>
> Hi all,
>
> I think that the changes should be considered in the light of another fact: the updating of the documentation. I don't know where/when to integrate it but keep in mind that the docs team is also interested in a clear, detailed, non-developer oriented description generated issue reports.
Yes I think we can make a workflow where it goes from PR -> Changelog -> Docs. I’d like to give Charles a little time to get used to the workflows (we have been documenting it at https://github.com/qgis/QGIS/wiki/Changelog-Workflows <https://github.com/qgis/QGIS/wiki/Changelog-Workflows>) and then we can figure out how to incorporate that additional step.
Regards
Tim
>
> On a related note, I would like feedback on where we stand with the use of the "needs documentation" label for new features.
> My feeling is that while it gets adopted in earlier stages, it's now almost unused [0]. It would be interesting to know "why?". I still see a lot of [feature] tag use in commits which does not provide the potentially fancy things in the PR. For information, the feature_tracker current system will be deprecated by github this autumn [1] and in order to keep all our machinery at a single place, the feature_tracker system won't be updated (Denis, Richard?) so these tags will not work in a few months.
>
> [0] recent features: https://github.com/qgis/QGIS/pulls?q=is%3Apr+label%3AFeature+sort%3Aupdated-desc+is%3Aclosed <https://github.com/qgis/QGIS/pulls?q=is%3Apr+label%3AFeature+sort%3Aupdated-desc+is%3Aclosed>
> [1] https://developer.github.com/changes/2020-02-14-deprecating-password-auth/ <https://developer.github.com/changes/2020-02-14-deprecating-password-auth/>
>
> Regards,
> Harrissou
>
> Le mar. 7 juil. 2020 à 10:02, Tim Sutton <tim at kartoza.com <mailto:tim at kartoza.com>> a écrit :
> Hi
>
>> On 7 Jul 2020, at 08:26, Matthias Kuhn <matthias at opengis.ch <mailto:matthias at opengis.ch>> wrote:
>>
>> Thanks Charles and Tim,
>>
>> I this kind of semi-automated process with clear rules is a very good balance for increasing changelog quality and decreasing the load on developers to write changelog entries last minute.
>>
>>
>
> Great - I was thinking we should put the notes from this thread somewhere so that people can discover it…..maybe in the PR template like we have for bug reports?
>
>> If we want some tech-fancy stuff in the backend, a github workflow could be written that checks for the "Feature" label. If that tag is present it will require either a `# Changelog` title or a "No Changelog" label. As long as this is missing it will not be possible to merge. Happy to lend a hand if you want to follow this road.
>>
>>
>
> Yes that would be super if Nyall and friends agree, thanks! It will go a long way to making sure that things dont get merged if they are features and are not clear enough for the changelog writers.
>
> If you or Nyall are up for adding Changelog fields in the PR template for ‘Feature’ designated PR's here are the data items we include for each entry:
>
> Category one of:
>
> 3D Features
> Analysis Tools
> Application and Project Options
> Browser
> Data Management
> Data Providers
> Diagrams
> Digitising
> Documentation
> Expressions
> Forms and Widgets
> General
> Labelling
> Layer Legend
> Map Tools
> Mesh
> Notable Fixes
> Plugins
> Print Layouts
> Processing
> Programmability
> QGIS Server
> Rendering
> Symbology
> Temporal
> User Interface
>
> Feature Title: (probably same as PR title)
>
> Description: Maybe we can have a section in the PR called "Changelog End User Description:”
>
> Feature image:
>
> Image credits:
>
> Video link:
>
> Funded by:
>
> Funder URL:
>
> Developed by:
>
> Developer URL:
>
>
>
>
> Regards
>
> Tim
>
>> Matthias
>>
>> On 7/7/20 8:56 AM, Tim Sutton wrote:
>>> Hi
>>>
>>>> On 7 Jul 2020, at 01:19, Nyall Dawson <nyall.dawson at gmail.com <mailto:nyall.dawson at gmail.com>> wrote:
>>>>
>>>> Hi Tim,
>>>>
>>>> Thanks for your hard work here!
>>>>
>>>>> 2) Tasked Charles to read each PR that has a ‘Feature’ label as it comes in and in the comments section, nudge the author if the description is not clear / well described. Would be grateful if the PR gatekeepers could hold back on merging Feature PR’s that have issues, do not have a Changelog tag applied. Note that the English doesn’t need to be perfect (we are understanding that English may not be your mother toungue), the important thing is that the functionality is well described - we will tidy up the English in step 6 below.
>>>>> 3) Once the PR description is good, Charles will add the ‘Changelog’ tag to it.
>>>>
>>>> To clarify -- we DON'T manually add the changelog tag to anything?
>>>> Just the feature tag is sufficient?
>>>
>>> Correct - Charles will add the tag when we want to ingest it so we will have 3 states basically:
>>>
>>> 1) Feature tag - not ready for ingestion in Changelog
>>> 2) Feature tag + Changelog tag + PR Merged - ready for ingestion
>>> 3) Feature tag + ChangelogHarvested tag + PR merged - entry has been ingested
>>>
>>>
>>>>
>>>> One potential reservation I have with this process is that it means
>>>> that PR descriptions need to be user-focused, rather then developer
>>>> focused. I think this is a bit backwards -- for review purposes it's
>>>> better to focus the PR comment on the technical details rather than
>>>> just using the "glossy overview" that we want for the changelog.
>>>
>>> I think it is fine gif it is developer focussed but would be great if there was enough substance that Charles / changlog writers could convert the info there into something user facing - screenshot would also be nice
>>>
>>>
>>>>
>>>> Could we do something fancy like add a section in the PR template for
>>>> "changelog entry" and only harvest this part for the changelog?
>>>
>>>
>>> Yes indeed - if we could mirror the fields for a changelog entry record that would be awesome - we could put the nerdy stuff outside of the user facing part. Can you help with that?
>>>
>>> Thanks!
>>>
>>> Regards
>>>
>>> Tim
>>>
>>>
>>>>
>>>> Nyall
>>>>
>>>>
>>>>
>>>>
>>>>
>>>>>
>>>>> 4) Once the PR is merged, we will regularly Harvest the ‘Changelog tagged entries to the Changelog site.
>>>>>
>>>>> 5) We have added an additional tag on GitHub called ‘ChangelogHarvested’ which will be applied after and entry is harvested, and the Changelog tag then removed (and should bot be readied to avoid duplicates being pulled in).
>>>>>
>>>>> 6) The entry will then be tidied up on the changelog site ready for the release. Additional volunteers (e.g. Toto, Frank) who have helped in the past are warmly invited to help improve the clarity and consistency of the entries on the changelog site.
>>>>>
>>>>> 7) When the release comes near we just need the paid bug fixing entries added (usually managed by Andreas Neumann) and then Richard can pull the changelog to the QGIS web site.
>>>>>
>>>>>
>>>>> I have started the Changelog for 3.16 here: https://changelog.qgis.org/en/qgis/version/3.16/ <https://changelog.qgis.org/en/qgis/version/3.16/>
>>>>>
>>>>>
>>>>> I hope that works for everyone, and that we get smoother changelog production in the future!
>>>>>
>>>>> Regards
>>>>>
>>>>> Tim
>>>>>
>>>>>
>>>>>
>>>>> —
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>> Tim Sutton
>>>>>
>>>>> Co-founder: Kartoza
>>>>> Honorary PSC Member and Ex-Project chair: QGIS.org <http://qgis.org/>
>>>>>
>>>>> Visit http://kartoza.com <http://kartoza.com/> to find out about open source:
>>>>>
>>>>> Desktop GIS programming services
>>>>> Geospatial web development
>>>>> GIS Training
>>>>> Consulting Services
>>>>>
>>>>> Skype: timlinux
>>>>> IRC: timlinux on #qgis at freenode.net <http://freenode.net/>
>>>>>
>>>>> I'd love to connect. Here's my calendar link to make finding time easy.
>>>>>
>>>>> _______________________________________________
>>>>> Qgis-psc mailing list
>>>>> Qgis-psc at lists.osgeo.org <mailto:Qgis-psc at lists.osgeo.org>
>>>>> https://lists.osgeo.org/mailman/listinfo/qgis-psc <https://lists.osgeo.org/mailman/listinfo/qgis-psc>
>>> —
>>>
>>>
>>>
>>> <KartozaNewLogoThumbnail.jpg>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>> Tim Sutton
>>>
>>> Co-founder: Kartoza
>>> Honorary PSC Member and Ex-Project chair: QGIS.org <http://qgis.org/>
>>>
>>> Visit http://kartoza.com <http://kartoza.com/> to find out about open source:
>>>
>>> Desktop GIS programming services
>>> Geospatial web development
>>> GIS Training
>>> Consulting Services
>>>
>>> Skype: timlinux
>>> IRC: timlinux on #qgis at freenode.net <http://freenode.net/>
>>>
>>> I'd love to connect. Here's my calendar link <https://calendly.com/timlinux/30min> to make finding time easy.
>>>
>>>
>>>
>>> _______________________________________________
>>> Qgis-psc mailing list
>>> Qgis-psc at lists.osgeo.org <mailto:Qgis-psc at lists.osgeo.org>
>>> https://lists.osgeo.org/mailman/listinfo/qgis-psc <https://lists.osgeo.org/mailman/listinfo/qgis-psc>
> —
>
>
>
> <KartozaNewLogoThumbnail.jpg>
>
>
>
>
>
>
>
>
> Tim Sutton
>
> Co-founder: Kartoza
> Honorary PSC Member and Ex-Project chair: QGIS.org <http://qgis.org/>
>
> Visit http://kartoza.com <http://kartoza.com/> to find out about open source:
>
> Desktop GIS programming services
> Geospatial web development
> GIS Training
> Consulting Services
>
> Skype: timlinux
> IRC: timlinux on #qgis at freenode.net <http://freenode.net/>
>
> I'd love to connect. Here's my calendar link <https://calendly.com/timlinux/30min> to make finding time easy.
>
> _______________________________________________
> Qgis-psc mailing list
> Qgis-psc at lists.osgeo.org <mailto:Qgis-psc at lists.osgeo.org>
> https://lists.osgeo.org/mailman/listinfo/qgis-psc <https://lists.osgeo.org/mailman/listinfo/qgis-psc>
—
Tim Sutton
Co-founder: Kartoza
Honorary PSC Member and Ex-Project chair: QGIS.org <http://qgis.org/>
Visit http://kartoza.com <http://kartoza.com/> to find out about open source:
Desktop GIS programming services
Geospatial web development
GIS Training
Consulting Services
Skype: timlinux
IRC: timlinux on #qgis at freenode.net
I'd love to connect. Here's my calendar link <https://calendly.com/timlinux/30min> to make finding time easy.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20200714/85fb791e/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: KartozaNewLogoThumbnail.jpg
Type: image/jpeg
Size: 6122 bytes
Desc: not available
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20200714/85fb791e/attachment-0001.jpg>
More information about the QGIS-Developer
mailing list