[Pulp-dev] Release Note Process Improvements

Tue Jun 4 14:37:32 UTC 2019

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