[Pulp-dev] Changelog conventions

[Tatiana Tereshchenko]

+1 to describe the fix and not the problem.

On Thu, Mar 12, 2020 at 12:43 AM Dana Walker <dawalker at redhat.com> wrote:

> +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
>>
> _______________________________________________
> 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/20200312/09ee7106/attachment.htm>