Open Stack

Excerpts from Doug Hellmann's message of 2016-02-28 10:40:44 -0500:
> Excerpts from Thomas Goirand's message of 2016-02-28 22:56:51 +0800:
> > On 02/28/2016 01:18 AM, Davanum Srinivas wrote:
> > > Thomas,
> > > 
> > > Please try and let use know what kind of problems you see in Debian as
> > > projects have already switched to reno.
> > 
> > Dims,
> > 
> > Unfortunately, if I wrote about this, that's because I tried, and
> > experienced not very nice things packaging Mitaka b1 and b2. I sometimes
> > had to patch out the reno sphinx module to be able to build the sphinx
> > docs of some packages. For example:
> > 
> > http://anonscm.debian.org/cgit/openstack/python-os-client-config.git/tree/debian/patches/remove-the-use-of-reno.patch?h=debian/mitaka
> > 
> > I don't think the above patch is the way to go, because:
> > - We should address this in a more general way, not on individual
> > (Debian) packages
> > - Running "sphinx-build" should always work, no mater what
> > - The release notes also belongs in a Debian package
> > 
> > I already wrote about it to Doug. I opened a general topic about not
> > using git (and more specifically in this case: "git log") when
> > generating the documentation (see below the reference to the thread).
> > But it's looking like that's still not enough. :(
> > 
> > > I believe Thomas is referring to:
> > >
> > >     https://bugs.launchpad.net/reno/+bug/1520096
> > 
> > The funny part about this bug is that it was opened against Reno, which
> > by design, is doing things wrongly. Then the issue was kind of turned
> 
> Please try to remember that your use case is not the only use case we
> have. Reno was designed to meet a very specific set of criteria and
> requirements to solve a problem the release team identified. Building
> release notes documents without git history has been on the list of
> requirements for quite some time, we just haven't gotten to it yet.
> 
> > around, and fixed in python-neutronclient. However, many other packages
> > have the problem too, and I don't believe that they will somehow all be
> > magically fixed and understand what should be done or not.
> > 
> > To me, the issue should really be fixed into Reno itself (if it is even
> > fixable...).
> > 
> > By the way, this bug was opened in November, even before Mitaka b1,
> > which gave enough time to understand that Reno isn't working the way it
> > should (ie: it relies on git at "sphinx-build" time, which it shouldn't).
> > 
> > One way I would see to fix the issue, would be having Reno to actually
> > write the release notes in an RST format, but just *not* when invoking
> > sphinx-build. Then such a generated file could be stored in the Git
> > repository of each individual projects, plus a gate job for checking
> > it's up-to-date could be written. That's of course just an idea, and as
> > I maintain all of OpenStack packages in Debian (350 source packages and
> > counting...), I unfortunately can't volunteer to implement it. :/
> 
> No, we won't be checking compiled documents into git. The history of
> doing that with configuration sample files, and other generated pages,
> has clearly demonstrated that to be a bad solution to this type of
> problem. I've outlined the approach we have planned in my other email so
> I won't repeat it here.
> 
> > 
> > >
> > http://lists.openstack.org/pipermail/openstack-dev/2016-February/thread.html#86917
> > 
> > Yeah, that's the thread I am referring to above. Thanks Steve, for
> > pointing it out so I don't have to do the search myself! :)
> > 
> > It is still my view that projects should revert using Reno asap until
> > the issue is fixed in Reno. Sure, I could potentially open a bug for
> > each and every package which has the issue, but IMO that's not the way
> > to go.
> 
> Projects should not use reno in their developer documentation. They
> should use a separate sphinx build set up to run under "tox -e
> releasenotes" with the relevant CI jobs to ensure the results are
> published under docs.openstack.org/releasenotes. None of that will
> interfere with your packaging.

I should expand on this point. Early on, I did suggest that projects
without deployer-facing notes *could* do this. But since earlier
discussions of the issues related to packaging came up, we've revised
that advice to say that all projects should split their docs and release
notes. This may not have been widely implemented, so where you're
encountering issues please file bugs. It's relatively simple to fix the
projects for this cycle, in case we don't get the git-free scanner for
reno implemented this cycle.

> 
> > 
> > By the way, Reno itself is doing so many gpg keys that the system
> > building it can't have enough entropy, and then the unit tests are
> > timing-out. Is there a way to fix this?
> 
> Give this a try and see if it works any better:
> https://review.openstack.org/285812
> 
> Doug