[Pulp-dev] Release Note Process Improvements

Thu Jun 6 11:42:37 UTC 2019

The one thing that wasn't clear to me after reading the docs was how the
different categories (feature, bugfix, removal, etc) were defined. I didn't
notice it while reading the towncrier README so I just want point it out
for others who may not know:

https://github.com/hawkowl/towncrier#news-fragments

David

On Thu, Jun 6, 2019 at 7:13 AM Ina Panova <ipanova at redhat.com> wrote:

> Thank you Brian for moving this forward. That's a good improvement!
>
>
> --------
> 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 Tue, Jun 4, 2019 at 4:39 PM Brian Bouterse <bbouters at redhat.com> wrote:
>
>> The towncrier release process [0] is now in place for the repositories
>> below. Although this proposal discussed adoption for pulpcore specifically,
>> in collaboration w/ plugin teams on IRC, it was applied more broadly.
>>
>> pulpcore, pulpcore-plugin, plugin_template, pulp_file, pulp_rpm,
>> pulp_ansible, pulp_docker, pulp_python, pulp-certguard
>>
>> ## Start adding release notes
>> Each plugin got doc updates w/ the process on how to add release notes
>> now. Please start checking these notes in in all ^ repos w/ your commits.
>>
>> ## See what it looks like
>> You can run `towncrier --draft` in the root of any ^ repo and it'll print
>> out the release notes it would have produced. If you run it without --draft
>> it will add the actual content to CHANGES.rst and stage those changes. When
>> you run it without --draft it prompts to remove all the notes from CHANGES
>> so once they go to the changelog they don't get regnerated. So that means
>> we only generate just before we release and if you want to know what's
>> different in source look at the CHANGES directory directly.
>>
>> ## File Usages
>> The CHANGES.rst is intended for the changelog for the most recent release
>> only. The HISTORY.rst file contains the changelogs of all previous releases
>> appended. The Sphinx docs bring both of these files together as if they are
>> on on the documentation site, this is just a common Python file arrangement
>> I've seen in many successful projects. This means that you'll want to move
>> contents from the CHANGES.rst file to the HISTORY.rst periodically.
>>
>> ## Gotchas
>> The very first set of notes you produce need a tiny manual touchup to
>> remove the '-------' at the end. Otherwise Sphinx will fail to build.
>> Subsequent generated notes will require no updates (so the template is
>> already correct). After you run towncrier you can run Sphinx locally to be
>> sure you're generated notes are good to go.
>>
>> ## Adding to your plugin
>> To adopt a similar change in $your_plugin this is probably the best PR to
>> look at: https://github.com/pulp/pulp_python/pull/245
>>
>> ## Version string duplication
>> FYI, also with this work all the above repos got version string
>> duplication. While working on ^, towncrier wanted a __version__ and I
>> learned that de-duplicating across setup.py and __version__ is kind of
>> hazardous. So after much back-and-forth the current pattern looks like
>> this:   https://github.com/pulp/pulp_rpm/pull/1363/files   The issues
>> motivating this design is that setup.py isn't around on installed systems,
>> and both towncrier and Read The Docs want to know __version__ but *dont'*
>> want to install the package.
>>
>> I plan to send another proposal this week on adopting 'bumpversion' so we
>> never get this duplicated aspect wrong. Any questions or concerns on what
>> has been already done is welcome.
>>
>> [0]: https://pulp.plan.io/projects/pulp/wiki/Pulp3_Release_Guide
>>
>> Thanks,
>> Brian
>>
>>
>>
>> On Tue, May 28, 2019 at 4:00 PM Brian Bouterse <bbouters at redhat.com>
>> wrote:
>>
>>> Great with the issue groomed, and much +1 feedback I think we should put
>>> it in place soon so we can start having an accurate changelog for rc3. I am
>>> planning to pick this up and so I've taken the issue as assigned. I'll post
>>> PRs on this thread so everyone can see once they area available (hopefully
>>> tomorrow or Thurs at latest).
>>>
>>> More comments, ideas, or concerns are also welcome.
>>>
>>> On Tue, May 28, 2019 at 3:53 PM Daniel Alley <dalley at redhat.com> wrote:
>>>
>>>> +1
>>>>
>>>> On Tue, May 28, 2019 at 2:23 PM Dennis Kliban <dkliban at redhat.com>
>>>> wrote:
>>>>
>>>>> +1
>>>>>
>>>>> I updated the task[0] slightly and marked it as groomed.
>>>>>
>>>>>
>>>>> [0] https://pulp.plan.io/issues/4875
>>>>>
>>>>> On Tue, May 28, 2019 at 12:14 PM Austin Macdonald <austin at redhat.com>
>>>>> wrote:
>>>>>
>>>>>> The proposed changes look awesome! I'm +1 for moving forward with it
>>>>>> for pulpcore and pulpcore-plugin.
>>>>>>
>>>>>> If there is consensus (looks like we are close), lets go ahead. If
>>>>>> anyone has concerns, we also have the option to implement this change for
>>>>>> one plugin before we go all in.
>>>>>>
>>>>>> On Mon, May 27, 2019 at 5:26 AM Ina Panova <ipanova at redhat.com>
>>>>>> wrote:
>>>>>>
>>>>>>> +1
>>>>>>>
>>>>>>>
>>>>>>> --------
>>>>>>> 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 Sat, May 25, 2019 at 10:18 PM Tatiana Tereshchenko <
>>>>>>> ttereshc at redhat.com> wrote:
>>>>>>>
>>>>>>>> +1 to improve release notes process
>>>>>>>>
>>>>>>>> If we decide to use PR numbers and not redmine issues in the
>>>>>>>> release notes, then there will be no limitation/requirement to have a
>>>>>>>> redmine issue to add something to the release notes.
>>>>>>>>
>>>>>>>> Tanya
>>>>>>>>
>>>>>>>> On Fri, May 24, 2019 at 3:46 PM David Davis <daviddavis at redhat.com>
>>>>>>>> wrote:
>>>>>>>>
>>>>>>>>> +1 to bmbouter's proposal and not including '[noissue]' items in
>>>>>>>>> release notes.
>>>>>>>>>
>>>>>>>>> David
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> On Fri, May 24, 2019 at 3:52 AM Matthias Dellweg <dellweg at atix.de>
>>>>>>>>> wrote:
>>>>>>>>>
>>>>>>>>>> I am fine with stating "[noissue] means 'not worth mentioning in
>>>>>>>>>> release notes'".
>>>>>>>>>> This would require the reviewer to decide to tell the
>>>>>>>>>> contributor: "We
>>>>>>>>>> want that to be part of the release notes. Please open up a
>>>>>>>>>> ticket."
>>>>>>>>>> And that process scales better than handpicking the notes in the
>>>>>>>>>> end.
>>>>>>>>>>
>>>>>>>>>> On Thu, 23 May 2019 16:22:36 -0400
>>>>>>>>>> Dana Walker <dawalker at redhat.com> wrote:
>>>>>>>>>>
>>>>>>>>>> > My initial thought is this looks useful to the user and very
>>>>>>>>>> clean.
>>>>>>>>>> > I've also found it to be a burden trying to write good release
>>>>>>>>>> notes,
>>>>>>>>>> > having to dig through commits and try to decide what's important
>>>>>>>>>> > enough and what's not, so +1 to trying to improve this process
>>>>>>>>>> for
>>>>>>>>>> > both the releaser and user.
>>>>>>>>>> >
>>>>>>>>>> > However:
>>>>>>>>>> > "towncrier works best in a development system where all merges
>>>>>>>>>> involve
>>>>>>>>>> > closing a ticket."
>>>>>>>>>> > We frequently make use of "[noissue]" in our PRs, in part to
>>>>>>>>>> lower the
>>>>>>>>>> > burden on contributors making small fixes.  Would we want to
>>>>>>>>>> move to a
>>>>>>>>>> > model where we *must* have an issue?  Are we instead assuming
>>>>>>>>>> those
>>>>>>>>>> > items are small enough that the user doesn't need to see it in
>>>>>>>>>> the
>>>>>>>>>> > release notes?
>>>>>>>>>> >
>>>>>>>>>> > Thoughts?
>>>>>>>>>> >
>>>>>>>>>> > --Dana
>>>>>>>>>> >
>>>>>>>>>> > Dana Walker
>>>>>>>>>> >
>>>>>>>>>> > She / Her / Hers
>>>>>>>>>> >
>>>>>>>>>> > Software Engineer, Pulp Project
>>>>>>>>>> >
>>>>>>>>>> > Red Hat <https://www.redhat.com>
>>>>>>>>>> >
>>>>>>>>>> > dawalker at redhat.com
>>>>>>>>>> > <https://www.redhat.com>
>>>>>>>>>> >
>>>>>>>>>> >
>>>>>>>>>> >
>>>>>>>>>> > On Thu, May 23, 2019 at 3:49 PM Brian Bouterse <
>>>>>>>>>> bbouters at redhat.com>
>>>>>>>>>> > wrote:
>>>>>>>>>> >
>>>>>>>>>> > > In discussion with some other devs, I've realized that
>>>>>>>>>> pulpcore and
>>>>>>>>>> > > pulpcore-plugin would benefit from better release notes. Here
>>>>>>>>>> are
>>>>>>>>>> > > some of the reasons that have come up:
>>>>>>>>>> > >
>>>>>>>>>> > > * The release notes are incomplete. One person tries to go
>>>>>>>>>> through
>>>>>>>>>> > > and write release notes just before the release happens, and
>>>>>>>>>> by
>>>>>>>>>> > > that point, the number of changes are too many for this
>>>>>>>>>> approach to
>>>>>>>>>> > > produce complete and robust notes.
>>>>>>>>>> > > * They are hard to produce. Producing "all the release notes"
>>>>>>>>>> is a
>>>>>>>>>> > > mentally difficult task.
>>>>>>>>>> > > * We try to substitute with Redmine, but this approach limits
>>>>>>>>>> us
>>>>>>>>>> > > (a) it's now difficult and time consuming to see what
>>>>>>>>>> changed, (b)
>>>>>>>>>> > > there is way more detail than you actually want, and they
>>>>>>>>>> aren't
>>>>>>>>>> > > self-contained (can't be browsed off-line).
>>>>>>>>>> > > * overall all ^ leads to both users and plugin writers feeling
>>>>>>>>>> > > uncertain about what has changed in the last release, week,
>>>>>>>>>> or even
>>>>>>>>>> > > day.
>>>>>>>>>> > >
>>>>>>>>>> > > So what can we do? Recently I contributed to aiohttp and I
>>>>>>>>>> found
>>>>>>>>>> > > their release note process light and easy. It produces
>>>>>>>>>> high-quality
>>>>>>>>>> > > release notes like these:
>>>>>>>>>> > > https://aiohttp.readthedocs.io/en/stable/changes.html
>>>>>>>>>> > >
>>>>>>>>>> > > You can read about their process here:
>>>>>>>>>> > >
>>>>>>>>>> https://aiohttp.readthedocs.io/en/stable/contributing.html#changelog-update
>>>>>>>>>> > > You can see some examples of these release note files in
>>>>>>>>>> their repo
>>>>>>>>>> > > here: https://github.com/aio-libs/aiohttp/tree/master/CHANGES
>>>>>>>>>> > > Overall it makes use of the towncrier project
>>>>>>>>>> > > https://github.com/hawkowl/towncrier
>>>>>>>>>> > >
>>>>>>>>>> > > What do you all think about trying something like this for
>>>>>>>>>> pulpcore
>>>>>>>>>> > > and pulpcore-plugin? Please write back on-list with thoughts,
>>>>>>>>>> > > ideas, concerns, alternatives, etc.
>>>>>>>>>> > >
>>>>>>>>>> > > Also, I made us a starter issue to coalesce some more of the
>>>>>>>>>> > > practical aspect of adopting a change like this:
>>>>>>>>>> > > https://pulp.plan.io/issues/4875
>>>>>>>>>> > >
>>>>>>>>>> > > All the best,
>>>>>>>>>> > > Brian
>>>>>>>>>> > >
>>>>>>>>>> > >
>>>>>>>>>> > >
>>>>>>>>>> > > _______________________________________________
>>>>>>>>>> > > 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
>>>>
>>> _______________________________________________
>> 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/20190606/20897bb7/attachment.htm>