[Pulp-dev] Changelog conventions

Fri Mar 13 17:52:41 UTC 2020

I took a look at django's release notes[0] and they seem to do a good job.
They use past simple tense for the most part so I went with that. Here's a
PR:

https://github.com/pulp/pulpcore/pull/579

Feedback welcome!

[0] https://docs.djangoproject.com/en/3.0/releases/

David

On Thu, Mar 12, 2020 at 2:01 PM Tatiana Tereshchenko <ttereshc at redhat.com>
wrote:

> +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
>>
> _______________________________________________
> 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/20200313/8e363fc0/attachment.htm>