[openstack-dev] [reno] questions about reno

Doug Hellmann doug at doughellmann.com
Mon Jan 8 19:03:37 UTC 2018

Excerpts from Gaetan's message of 2018-01-08 17:59:55 +0100:
> Hello
> Thanks for your answers!
> - unreleased notes appear in release note with a title such as "0.1.0-2".
> > > Is it possible to not have any title or use "0.1.0-dev2" pattern like
> > pbr ?
> >
> > I'm not sure why it matters, but if you want to work on that patch I'll
> > help with reviews.
> >
> Ok, I'll see what I can do :)
> >
> > > - I guess that all notes should stay in the same folder version after
> > > versions, and the
> > > release notes of all versions will keep being automatically generated.
> > > Don't you think
> > > it might get difficult to manage all theses files? Is is possible to move
> > > them in different folder (at least a folder "archives?)
> >
> > We've put off doing anything like that until we have a project with
> > enough notes that we can observe the problems and decide how to fix
> > them. Have you already reached that point or are you anticipating
> > problems in the future?
> >
> No, just started using reno and just see that this folder might get messy
> quickly. Maybe I over-think this, I agree with you to observe first
> >
> > > - it is possible to generate the NEWS file using reno ? I started trying
> > > conversion with pandoc but the result are not great.
> >
> > How is the NEWS file different from CHANGES.txt that pbr produces? Is it
> > the format, or the content?
> >
> So, I like PBR that generates ChangeLog from the git history, but it has
> lot of details (maybe too much). So, I was thinking to store in NEWS only
> the release note
> As an example, you can look how I plan to use it for Guake:
> https://github.com/Guake/guake
> I usually write the NEWS at each release manually (
> https://github.com/Guake/guake/blob/master/NEWS), and that's where reno
> shines in my eyes :)

That looks similar to the output of the report command, although maybe
with less detail.

I can see a couple of ways to do this.

1. Use the report format as it is now.

2. Add a section to the note file to include a "highlight" or "news"
   entry that is ignored most of the time but can be used to produce
   summaries like this.

3. Try to somehow derive a summary from the text in the notes

Option 1 might work, although maybe you would end up with more detail
than you really want? If you were able to go this route, you could take
advantage of our plans to include release notes in source distributions
automatically (so you wouldn't even need to check the file into git).

Option 2 is do-able, but I'm a little concerned that having "magic"
sections makes the processing of the input files more complicated so
I'll have to think about whether it's really a good idea or not.

Option 3 sounds relatively hard, given that release notes just need to
be valid restructuredtext (meaning they don't need to be a list or other
structure that would be easy to take the "first" part of.


More information about the OpenStack-dev mailing list