<div dir="ltr">Thank you Brian for moving this forward. That's a good improvement!<br clear="all"><div><div><div dir="ltr" class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div><div dir="ltr"><br><br>--------<br>Regards,<br><br>Ina Panova<br>Senior Software Engineer| Pulp| Red Hat Inc.<br><br>"Do not go where the path may lead,<br> go instead where there is no path and leave a trail."<br></div></div></div></div></div><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Tue, Jun 4, 2019 at 4:39 PM Brian Bouterse <<a href="mailto:bbouters@redhat.com">bbouters@redhat.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div>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.</div><div><br></div><div>pulpcore, pulpcore-plugin, plugin_template, pulp_file, pulp_rpm, pulp_ansible, pulp_docker, pulp_python, pulp-certguard</div><div><br></div><div>## Start adding release notes</div><div>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.<br></div><div><br></div><div>## See what it looks like</div><div>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.</div><div><br></div><div>## File Usages<br></div><div>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.<br></div><div><br></div><div>## Gotchas</div><div>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.<br></div><div><br></div><div>## Adding to your plugin</div><div>To adopt a similar change in $your_plugin this is probably the best PR to look at: <a href="https://github.com/pulp/pulp_python/pull/245" target="_blank">https://github.com/pulp/pulp_python/pull/245</a></div><div><br></div><div>## Version string duplication</div><div>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:   <a href="https://github.com/pulp/pulp_rpm/pull/1363/files" target="_blank">https://github.com/pulp/pulp_rpm/pull/1363/files</a>   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.</div><div><br></div><div>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.<br></div><div><br></div><div>[0]: <a href="https://pulp.plan.io/projects/pulp/wiki/Pulp3_Release_Guide" target="_blank">https://pulp.plan.io/projects/pulp/wiki/Pulp3_Release_Guide</a></div><div><br></div><div>Thanks,</div><div>Brian</div><div><br></div><div><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Tue, May 28, 2019 at 4:00 PM Brian Bouterse <<a href="mailto:bbouters@redhat.com" target="_blank">bbouters@redhat.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div>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).<br></div><div><br></div><div>More comments, ideas, or concerns are also welcome.<br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Tue, May 28, 2019 at 3:53 PM Daniel Alley <<a href="mailto:dalley@redhat.com" target="_blank">dalley@redhat.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr">+1<br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Tue, May 28, 2019 at 2:23 PM Dennis Kliban <<a href="mailto:dkliban@redhat.com" target="_blank">dkliban@redhat.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div>+1 <br></div><div><br></div><div>I updated the task[0] slightly and marked it as groomed.</div><div><br></div><div><br></div><div>[0] <a href="https://pulp.plan.io/issues/4875" target="_blank">https://pulp.plan.io/issues/4875</a></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Tue, May 28, 2019 at 12:14 PM Austin Macdonald <<a href="mailto:austin@redhat.com" target="_blank">austin@redhat.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div>The proposed changes look awesome! I'm +1 for moving forward with it for pulpcore and pulpcore-plugin.<br></div><br><div>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.<br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, May 27, 2019 at 5:26 AM Ina Panova <<a href="mailto:ipanova@redhat.com" target="_blank">ipanova@redhat.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr">+1<br clear="all"><div><div dir="ltr" class="gmail-m_905753344541390080gmail-m_2816665427366604254gmail-m_5948959475982825747gmail-m_3791526295224589105gmail-m_2091389321331041829gmail-m_-5781104574369743950gmail-m_-1576529425612157844gmail-m_-1069074313603648146gmail_signature"><div dir="ltr"><div><div dir="ltr"><br><br>--------<br>Regards,<br><br>Ina Panova<br>Senior Software Engineer| Pulp| Red Hat Inc.<br><br>"Do not go where the path may lead,<br> go instead where there is no path and leave a trail."<br></div></div></div></div></div><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Sat, May 25, 2019 at 10:18 PM Tatiana Tereshchenko <<a href="mailto:ttereshc@redhat.com" target="_blank">ttereshc@redhat.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div></div><div></div><div>+1 to improve release notes process</div><div><br></div><div>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.</div><div><br></div><div>Tanya<br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Fri, May 24, 2019 at 3:46 PM David Davis <<a href="mailto:daviddavis@redhat.com" target="_blank">daviddavis@redhat.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr">+1 to bmbouter's proposal and not including '[noissue]' items in release notes.<br clear="all"><div><div dir="ltr" class="gmail-m_905753344541390080gmail-m_2816665427366604254gmail-m_5948959475982825747gmail-m_3791526295224589105gmail-m_2091389321331041829gmail-m_-5781104574369743950gmail-m_-1576529425612157844gmail-m_-1069074313603648146gmail-m_-6159603610953883988gmail-m_635808358011705696gmail_signature"><div dir="ltr"><div><div dir="ltr"><div><div dir="ltr"><div><br></div><div>David<br></div></div></div></div></div></div></div></div><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Fri, May 24, 2019 at 3:52 AM Matthias Dellweg <<a href="mailto:dellweg@atix.de" target="_blank">dellweg@atix.de</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">I am fine with stating "[noissue] means 'not worth mentioning in<br>
release notes'".<br>
This would require the reviewer to decide to tell the contributor: "We<br>
want that to be part of the release notes. Please open up a ticket."<br>
And that process scales better than handpicking the notes in the end.<br>
<br>
On Thu, 23 May 2019 16:22:36 -0400<br>
Dana Walker <<a href="mailto:dawalker@redhat.com" target="_blank">dawalker@redhat.com</a>> wrote:<br>
<br>
> My initial thought is this looks useful to the user and very clean.<br>
> I've also found it to be a burden trying to write good release notes,<br>
> having to dig through commits and try to decide what's important<br>
> enough and what's not, so +1 to trying to improve this process for<br>
> both the releaser and user.<br>
> <br>
> However:<br>
> "towncrier works best in a development system where all merges involve<br>
> closing a ticket."<br>
> We frequently make use of "[noissue]" in our PRs, in part to lower the<br>
> burden on contributors making small fixes.  Would we want to move to a<br>
> model where we *must* have an issue?  Are we instead assuming those<br>
> items are small enough that the user doesn't need to see it in the<br>
> release notes?<br>
> <br>
> Thoughts?<br>
> <br>
> --Dana<br>
> <br>
> Dana Walker<br>
> <br>
> She / Her / Hers<br>
> <br>
> Software Engineer, Pulp Project<br>
> <br>
> Red Hat <<a href="https://www.redhat.com" rel="noreferrer" target="_blank">https://www.redhat.com</a>><br>
> <br>
> <a href="mailto:dawalker@redhat.com" target="_blank">dawalker@redhat.com</a><br>
> <<a href="https://www.redhat.com" rel="noreferrer" target="_blank">https://www.redhat.com</a>><br>
> <br>
> <br>
> <br>
> On Thu, May 23, 2019 at 3:49 PM Brian Bouterse <<a href="mailto:bbouters@redhat.com" target="_blank">bbouters@redhat.com</a>><br>
> wrote:<br>
> <br>
> > In discussion with some other devs, I've realized that pulpcore and<br>
> > pulpcore-plugin would benefit from better release notes. Here are<br>
> > some of the reasons that have come up:<br>
> ><br>
> > * The release notes are incomplete. One person tries to go through<br>
> > and write release notes just before the release happens, and by<br>
> > that point, the number of changes are too many for this approach to<br>
> > produce complete and robust notes.<br>
> > * They are hard to produce. Producing "all the release notes" is a<br>
> > mentally difficult task.<br>
> > * We try to substitute with Redmine, but this approach limits us<br>
> > (a) it's now difficult and time consuming to see what changed, (b)<br>
> > there is way more detail than you actually want, and they aren't<br>
> > self-contained (can't be browsed off-line).<br>
> > * overall all ^ leads to both users and plugin writers feeling<br>
> > uncertain about what has changed in the last release, week, or even<br>
> > day.<br>
> ><br>
> > So what can we do? Recently I contributed to aiohttp and I found<br>
> > their release note process light and easy. It produces high-quality<br>
> > release notes like these:<br>
> > <a href="https://aiohttp.readthedocs.io/en/stable/changes.html" rel="noreferrer" target="_blank">https://aiohttp.readthedocs.io/en/stable/changes.html</a><br>
> ><br>
> > You can read about their process here:<br>
> > <a href="https://aiohttp.readthedocs.io/en/stable/contributing.html#changelog-update" rel="noreferrer" target="_blank">https://aiohttp.readthedocs.io/en/stable/contributing.html#changelog-update</a><br>
> > You can see some examples of these release note files in their repo<br>
> > here: <a href="https://github.com/aio-libs/aiohttp/tree/master/CHANGES" rel="noreferrer" target="_blank">https://github.com/aio-libs/aiohttp/tree/master/CHANGES</a><br>
> > Overall it makes use of the towncrier project<br>
> > <a href="https://github.com/hawkowl/towncrier" rel="noreferrer" target="_blank">https://github.com/hawkowl/towncrier</a><br>
> ><br>
> > What do you all think about trying something like this for pulpcore<br>
> > and pulpcore-plugin? Please write back on-list with thoughts,<br>
> > ideas, concerns, alternatives, etc.<br>
> ><br>
> > Also, I made us a starter issue to coalesce some more of the<br>
> > practical aspect of adopting a change like this:<br>
> > <a href="https://pulp.plan.io/issues/4875" rel="noreferrer" target="_blank">https://pulp.plan.io/issues/4875</a><br>
> ><br>
> > All the best,<br>
> > Brian<br>
> ><br>
> ><br>
> ><br>
> > _______________________________________________<br>
> > Pulp-dev mailing list<br>
> > <a href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a><br>
> > <a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/mailman/listinfo/pulp-dev</a><br>
> >  <br>
_______________________________________________<br>
Pulp-dev mailing list<br>
<a href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/mailman/listinfo/pulp-dev</a><br>
</blockquote></div>
_______________________________________________<br>
Pulp-dev mailing list<br>
<a href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/mailman/listinfo/pulp-dev</a><br>
</blockquote></div>
_______________________________________________<br>
Pulp-dev mailing list<br>
<a href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/mailman/listinfo/pulp-dev</a><br>
</blockquote></div>
_______________________________________________<br>
Pulp-dev mailing list<br>
<a href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/mailman/listinfo/pulp-dev</a><br>
</blockquote></div>
_______________________________________________<br>
Pulp-dev mailing list<br>
<a href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/mailman/listinfo/pulp-dev</a><br>
</blockquote></div>
_______________________________________________<br>
Pulp-dev mailing list<br>
<a href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/mailman/listinfo/pulp-dev</a><br>
</blockquote></div>
_______________________________________________<br>
Pulp-dev mailing list<br>
<a href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/mailman/listinfo/pulp-dev</a><br>
</blockquote></div>
</blockquote></div>
_______________________________________________<br>
Pulp-dev mailing list<br>
<a href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/mailman/listinfo/pulp-dev</a><br>
</blockquote></div>