[Pulp-dev] Changelog conventions

[David Davis]

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).

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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20200311/0cf75bc5/attachment.htm>