[openstack-dev] [stable] [infra] How to auto-generate stable release notes

Thierry Carrez thierry at openstack.org
Fri Aug 21 10:38:43 UTC 2015


Robert Collins wrote:
> On 19 August 2015 at 21:19, Thierry Carrez <thierry at openstack.org> wrote:
>>> Processing:
>>> 1) determine the revisions we need to generate release notes for. By
>>> default generate notes for the current minor release. (E.g. if the
>>> tree version is 1.2.3.dev4 we would generate release notes for 1.2.0,
>>> 1.2.1, 1.2.2, 1.2.3[which dev4 is leading up to]).
>>
>> How would that work in a post-versioned world ? What would you generate
>> if the tree version is 1.2.3.post12 ?
> 
> 1.2.3 is still the version, not that we can use post versions at all
> with pbr. (Short story - we can't because we used them wrongly and we
> haven't had nearly enough time to flush out remaining instances in the
> wild).

Could you expand on that ? Feels like I'm missing a piece of the puzzle.
Let's say we just tagged 1.2.3. The next commit is a security fix (for
which we don't know the OSSA number yet). The one after that is the
release-notes/???.yaml change which specifies the OSSA number in the
release notes. At this point we still have no idea what the next version
number will look like, since there is no tag yet. What should the
filename for ???.yaml be in that case ? If you workaround that by
referencing the OSSA in the changes/$ChangeID.yaml file instead, what
(if any) work-in-progress .md file does that end up generating ?

If we want to serve partial release notes for people consuming the
stable branch between tag points, for repositories using post-versioning
we have to produce some "next.md" or "in-progress.md" since we can't
guess what the next version will actually be.

>> [...]
>>> If we want to put release notes in sdists, we can have pbr do this,
>>> otherwise it could just be built entirely separately.
>>
>> I think we need to put release notes in sdists, so that people consuming
>> stable branches from a random commit can still get work-in-progress
>> releasenotes for the upcoming version.
> 
> Those two things are disconnected. Consuming a random commit doesn't
> imply sdist - nor does it preclude it.
> 
> We don't *currently* generate release notes in sdists. Whats the
> driver for adding it? [perhaps as a use case so we can flush out
> hidden assumptions we have]

The whole idea behind moving away from coordinated stable branch
releases is to let people consume the stable branch at any point in
time. The original plan was to stop releasing (tagging) stable branches
completely. People replied they still needed "release notes" so that
they have upgrade warnings and other bits of information about what they
are getting. It's inconvenient to continue using wiki pages to achieve
that, so we moved to in-git maintenance of release notes. And rather
than force consumers to generate them from the tree, they can
conveniently find them in any stable source code tarball we publish
(including intermediary ones like $project-stable-kilo.tar.gz).

Since then, replying to another concern about common downstream
reference points, we moved to "tagging everything", then replying to
Clark's pollution remark, to "tag from time to time". That doesn't
remove the need to *conveniently* ship the best release notes we can
with every commit. Including them in every code tarball (and relying on
well-known python sdist commands to generate them for those consuming
the git tree directly) sounded like the most accessible way to do it,
which the related thread on the Ops ML confirmed. But then I'm (and
maybe they are) still open to alternative suggestions...

Hope this clarifies,

-- 
Thierry Carrez (ttx)



More information about the OpenStack-dev mailing list