[Pulp-dev] Changelog conventions

Fri Mar 13 18:11:48 UTC 2020

On Fri, Mar 13, 2020 at 1:53 PM David Davis <daviddavis at redhat.com> wrote:

> 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
>
This is great, thank you!

> 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
>>
> _______________________________________________
> 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/1929d796/attachment.htm>