[Pulp-dev] Changelog conventions

[Dana Walker]

+1

Dana Walker

She / Her / Hers

Software Engineer, Pulp Project

Red Hat <https://www.redhat.com>

dawalker at redhat.com
<https://www.redhat.com>



On Wed, Mar 11, 2020 at 3:56 PM Dennis Kliban <dkliban at redhat.com> wrote:

> On Wed, Mar 11, 2020 at 3:33 PM David Davis <daviddavis at redhat.com> wrote:
>
>> I want to reopen this thread for discussion as this topic has come up
>> again this week. I don't think we need very strict or detailed requirements
>> for changelog messages. But rather, some guidance around things like which
>> tense to use would be helpful to standardize the changelog and not cause us
>> to debate formatting in our PRs.
>>
>> Regarding tense, I think either past simple or present makes sense. I
>> also believe that the changelog message should describe the fix and not the
>> problem (unlike the associated redmine issue).
>>
>> +1 ... This works for me.
>
>
>
>> David
>>
>>
>> On Wed, Mar 4, 2020 at 9:23 AM Robin Chan <rchan at redhat.com> wrote:
>>
>>> Thanks for closing out this thread/topic, Lubos. That is a helpful
>>> practice.
>>>
>>> Given Ina's input, I see that as a concern, because best practice for
>>> bugs is to have a title or description of the behavior that is a problem
>>> and NOT the solution so that they can easily be found by others
>>> experiencing the same bug. Whereas with features, it is best to have a
>>> title or description of new behavior being added. So I can see that this
>>> would make it hard to standardize practices here.
>>>
>>> Robin Chan
>>>
>>> She/Her/Hers
>>>
>>> Satellite Software Engineering Manager - Pulp
>>>
>>> Red Hat <https://www.redhat.com>
>>>
>>> IRC: rchan
>>> <https://www.redhat.com>
>>>
>>>
>>>
>>> On Fri, Feb 28, 2020 at 6:04 AM Lubos Mjachky <lmjachky at redhat.com>
>>> wrote:
>>>
>>>> No inputs have been received for a week. Therefore, the changelog
>>>> conventions should remain the same. That is, basically, no rules, and no
>>>> conventions at all. I will continue using past simple on my own.
>>>>
>>>> On Mon, Feb 17, 2020 at 5:31 PM Ina Panova <ipanova at redhat.com> wrote:
>>>>
>>>>> Thank you for starting this thread.
>>>>>
>>>>> The format of the changelog is different because the usual practice is
>>>>> to re-use the title of the issue/story/task/refactor.
>>>>>
>>>>> If we want to create some standards than maybe we should start with
>>>>> the titles from redmine.
>>>>>
>>>>> --------
>>>>> Regards,
>>>>>
>>>>> Ina Panova
>>>>> Senior Software Engineer| Pulp| Red Hat Inc.
>>>>>
>>>>> "Do not go where the path may lead,
>>>>>  go instead where there is no path and leave a trail."
>>>>>
>>>>>
>>>>> On Mon, Feb 17, 2020 at 4:55 PM Lubos Mjachky <lmjachky at redhat.com>
>>>>> wrote:
>>>>>
>>>>>> Dear colleagues,
>>>>>>
>>>>>> I have recently noticed that our changelog often contains non-uniform
>>>>>> messages informing about particular changes.
>>>>>>
>>>>>> For instance, take a look at the changelogs in pulp_container (
>>>>>> https://pulp-container.readthedocs.io/en/latest/changes.html) or
>>>>>> pulpcore (https://docs.pulpproject.org/en/master/nightly/changes.html
>>>>>> ):
>>>>>> 1. As a user I can manage images in OCI format.
>>>>>> 2. Let users fetch the list of all distributed repositories via the
>>>>>> _catalog endpoint.
>>>>>> 3. Adds ability to build OCI images from Containerfiles.
>>>>>> 4. Added v2s2 to v2s1 converter.
>>>>>> 5. Allow administrators to add a signing service.
>>>>>> 6. Files stored on S3 and Azure now download with the correct
>>>>>> filename.
>>>>>>
>>>>>> As you can see, we are using there random tenses and sentence
>>>>>> structures. I am in favor of establishing one feasible convention for all
>>>>>> changelog messages. We should strive to use only one tense, e.g. past
>>>>>> simple. Then, the messages would rather look like this [0]:
>>>>>> 1. Removed the filter for the field 'digest'.
>>>>>> 2. Added support for mirror mode.
>>>>>>
>>>>>> Please feel free to support this idea or raise any concerns. If we
>>>>>> reach a viable consensus I will create a PR which will add a note about
>>>>>> acceptable changelog messages to the corresponding section here
>>>>>> https://docs.pulpproject.org/en/master/nightly/contributing/git.html#changelog-update.
>>>>>> Thank you in advance.
>>>>>>
>>>>>> [0] https://keepachangelog.com/en/1.0.0/#how
>>>>>> _______________________________________________
>>>>>> Pulp-dev mailing list
>>>>>> Pulp-dev at redhat.com
>>>>>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>>>>>
>>>>> _______________________________________________
>>>> Pulp-dev mailing list
>>>> Pulp-dev at redhat.com
>>>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>>>
>>> _______________________________________________
>>> Pulp-dev mailing list
>>> Pulp-dev at redhat.com
>>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>>
>> _______________________________________________
>> Pulp-dev mailing list
>> Pulp-dev at redhat.com
>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>
> _______________________________________________
> Pulp-dev mailing list
> Pulp-dev at redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20200311/c4e3a46a/attachment.htm>