[openstack-dev] [all] Please do *not* use git (and specifically "git log") when generating the docs

Paul Belanger pabelanger at redhat.com
Thu Feb 18 22:09:34 UTC 2016


On Fri, Feb 19, 2016 at 01:17:08AM +0800, Thomas Goirand wrote:
> Hi,
> 
> I've seen Reno doing it, then some more. It's time that I raise the
> issue globally in this list before the epidemic spreads to the whole of
> OpenStack ! :)
> 
> The last occurence I have found is in oslo.config (but please keep in
> mind this message is for all projects), which has, its doc/source/conf.py:
> 
> git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'",
>            "--date=local","-n1"]
> html_last_updated_fmt = subprocess.check_output(git_cmd,
>                                                 stdin=subprocess.PIPE)
> 
> Of course, the .git folder is *NOT* available when building a package in
> Debian (and more generally, in downstream distros). This means that this
> kind of joke *will* break the build of the packages when they also build
> the docs of your project. And consequently, the package maintainers have
> to patch out the above lines from conf.py. It'd be best if it wasn't
> needed to do so.
> 
> As a consequence, it is *not ok* to do "git log" anywhere in the sphinx
> docs. Please keep this in mind.
> 
> More generally, it is wrong to assume that even the git command is
> present. For Mitaka b2, I had to add git as build-dependency on nearly
> all server packages, otherwise they would FTBFS (fail to build from
> source). This is plain wrong and makes no sense. I hope this can be
> reverted somehow.
> 
> Thanks in advance for considering the above, and to try to see things
> from the package maintainer's perspective,
> Cheers,
> 
I ran into this in Fedora rawhide a few weeks ago. When talking to Doug in
-infra, there was some discussion to integrate into PBR.  To me, it is just
lacking functionality ATM. For the moment, I dropped reno support on the package
which is not major at this point.

I suspect it will take a few more release to allow packagers to properly use it.

> Thomas Goirand (zigo)
> 
> 
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



More information about the OpenStack-dev mailing list