Re: [Pulp-dev] Changelog conventions

[Ina Panova]

Looks good, thank you!



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 Fri, Mar 13, 2020 at 6:53 PM David Davis  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
>
> Feedback welcome!
>
> [0] https://docs.djangoproject.com/en/3.0/releases/
>
> David
>
>
> On Thu, Mar 12, 2020 at 2:01 PM Tatiana Tereshchenko 
> wrote:
>
>> +1 to describe the fix and not the problem.
>>
>> On Thu, Mar 12, 2020 at 12:43 AM Dana Walker  wrote:
>>
>>> +1
>>>
>>> Dana Walker
>>>
>>> She / Her / Hers
>>>
>>> Software Engineer, Pulp Project
>>>
>>> Red Hat 
>>>
>>> dawal...@redhat.com
>>> 
>>>
>>>
>>>
>>> On Wed, Mar 11, 2020 at 3:56 PM Dennis Kliban 
>>> wrote:
>>>
 On Wed, Mar 11, 2020 at 3:33 PM David Davis 
 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  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 
>>
>> IRC: rchan
>> 
>>
>>
>>
>> On Fri, Feb 28, 2020 at 6:04 AM Lubos Mjachky 
>> 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 
>>> 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 
 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
> 

Re: [Pulp-dev] Changelog conventions

[Brian Bouterse]

On Fri, Mar 13, 2020 at 1:53 PM David Davis  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 
> wrote:
>
>> +1 to describe the fix and not the problem.
>>
>> On Thu, Mar 12, 2020 at 12:43 AM Dana Walker  wrote:
>>
>>> +1
>>>
>>> Dana Walker
>>>
>>> She / Her / Hers
>>>
>>> Software Engineer, Pulp Project
>>>
>>> Red Hat 
>>>
>>> dawal...@redhat.com
>>> 
>>>
>>>
>>>
>>> On Wed, Mar 11, 2020 at 3:56 PM Dennis Kliban 
>>> wrote:
>>>
 On Wed, Mar 11, 2020 at 3:33 PM David Davis 
 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  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 
>>
>> IRC: rchan
>> 
>>
>>
>>
>> On Fri, Feb 28, 2020 at 6:04 AM Lubos Mjachky 
>> 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 
>>> 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 
 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
> 

Re: [Pulp-dev] Changelog conventions

[David Davis]

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 
wrote:

> +1 to describe the fix and not the problem.
>
> On Thu, Mar 12, 2020 at 12:43 AM Dana Walker  wrote:
>
>> +1
>>
>> Dana Walker
>>
>> She / Her / Hers
>>
>> Software Engineer, Pulp Project
>>
>> Red Hat 
>>
>> dawal...@redhat.com
>> 
>>
>>
>>
>> On Wed, Mar 11, 2020 at 3:56 PM Dennis Kliban  wrote:
>>
>>> On Wed, Mar 11, 2020 at 3:33 PM David Davis 
>>> 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  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 
>
> IRC: rchan
> 
>
>
>
> On Fri, Feb 28, 2020 at 6:04 AM Lubos Mjachky 
> 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 
>> 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 
>>> 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

Re: [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  wrote:

> +1
>
> Dana Walker
>
> She / Her / Hers
>
> Software Engineer, Pulp Project
>
> Red Hat 
>
> dawal...@redhat.com
> 
>
>
>
> On Wed, Mar 11, 2020 at 3:56 PM Dennis Kliban  wrote:
>
>> On Wed, Mar 11, 2020 at 3:33 PM David Davis 
>> 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  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 

 IRC: rchan
 



 On Fri, Feb 28, 2020 at 6:04 AM Lubos Mjachky 
 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  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 
>> 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@redhat.com
>>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>>
>> ___
> Pulp-dev mailing list
> Pulp-dev@redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>
 ___
 Pulp-dev mailing list
 Pulp-dev@redhat.com
 https://www.redhat.com/mailman/listinfo/pulp-dev

>>> ___
>>> 

Re: [Pulp-dev] Changelog conventions

[Dana Walker]

+1

Dana Walker

She / Her / Hers

Software Engineer, Pulp Project

Red Hat 

dawal...@redhat.com




On Wed, Mar 11, 2020 at 3:56 PM Dennis Kliban  wrote:

> On Wed, Mar 11, 2020 at 3:33 PM David Davis  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  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 
>>>
>>> IRC: rchan
>>> 
>>>
>>>
>>>
>>> On Fri, Feb 28, 2020 at 6:04 AM Lubos Mjachky 
>>> 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  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 
> 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@redhat.com
>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>
> ___
 Pulp-dev mailing list
 Pulp-dev@redhat.com
 https://www.redhat.com/mailman/listinfo/pulp-dev

>>> ___
>>> Pulp-dev mailing list
>>> Pulp-dev@redhat.com
>>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>>
>> ___
>> Pulp-dev mailing list
>> Pulp-dev@redhat.com
>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>
> ___
> Pulp-dev mailing list
> Pulp-dev@redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>

Re: [Pulp-dev] Changelog conventions

[Dennis Kliban]

On Wed, Mar 11, 2020 at 3:33 PM David Davis  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  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 
>>
>> IRC: rchan
>> 
>>
>>
>>
>> On Fri, Feb 28, 2020 at 6:04 AM Lubos Mjachky 
>> 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  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 
 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@redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>
 ___
>>> Pulp-dev mailing list
>>> Pulp-dev@redhat.com
>>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>>
>> ___
>> Pulp-dev mailing list
>> Pulp-dev@redhat.com
>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>
> ___
> Pulp-dev mailing list
> Pulp-dev@redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>
___
Pulp-dev mailing list
Pulp-dev@redhat.com
https://www.redhat.com/mailman/listinfo/pulp-dev

Re: [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  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 
>
> IRC: rchan
> 
>
>
>
> On Fri, Feb 28, 2020 at 6:04 AM Lubos Mjachky  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  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 
>>> 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@redhat.com
 https://www.redhat.com/mailman/listinfo/pulp-dev

>>> ___
>> Pulp-dev mailing list
>> Pulp-dev@redhat.com
>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>
> ___
> Pulp-dev mailing list
> Pulp-dev@redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>
___
Pulp-dev mailing list
Pulp-dev@redhat.com
https://www.redhat.com/mailman/listinfo/pulp-dev

Re: [Pulp-dev] Changelog conventions

[Robin Chan]

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 

IRC: rchan




On Fri, Feb 28, 2020 at 6:04 AM Lubos Mjachky  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  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 
>> 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@redhat.com
>>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>>
>> ___
> Pulp-dev mailing list
> Pulp-dev@redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>
___
Pulp-dev mailing list
Pulp-dev@redhat.com
https://www.redhat.com/mailman/listinfo/pulp-dev

Re: [Pulp-dev] Changelog conventions

[Lubos Mjachky]

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  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  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@redhat.com
>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>
>
___
Pulp-dev mailing list
Pulp-dev@redhat.com
https://www.redhat.com/mailman/listinfo/pulp-dev

Re: [Pulp-dev] Changelog conventions

[Ina Panova]

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  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@redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>
___
Pulp-dev mailing list
Pulp-dev@redhat.com
https://www.redhat.com/mailman/listinfo/pulp-dev

Re: [Pulp-dev] Changelog conventions

[David Davis]

Lubos,

+1 to past simple tense. +1 to updating our changelog docs.

Thank you for raising this issue.

David


On Mon, Feb 17, 2020 at 10:55 AM Lubos Mjachky  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@redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>
___
Pulp-dev mailing list
Pulp-dev@redhat.com
https://www.redhat.com/mailman/listinfo/pulp-dev

[Pulp-dev] Changelog conventions

[Lubos Mjachky]

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@redhat.com
https://www.redhat.com/mailman/listinfo/pulp-dev