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 <ipan...@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 <bbout...@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 <bbout...@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 <dal...@redhat.com> wrote: >>> >>>> +1 >>>> >>>> On Tue, May 28, 2019 at 2:23 PM Dennis Kliban <dkli...@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 <aus...@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 <ipan...@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 < >>>>>>> ttere...@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 <davidda...@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 <dell...@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 <dawal...@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> >>>>>>>>>> > >>>>>>>>>> > dawal...@redhat.com >>>>>>>>>> > <https://www.redhat.com> >>>>>>>>>> > >>>>>>>>>> > >>>>>>>>>> > >>>>>>>>>> > On Thu, May 23, 2019 at 3:49 PM Brian Bouterse < >>>>>>>>>> bbout...@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@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 >>>>>>> >>>>>> _______________________________________________ >>>>>> 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 >
_______________________________________________ Pulp-dev mailing list Pulp-dev@redhat.com https://www.redhat.com/mailman/listinfo/pulp-dev
