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

Javier Pena javier.pena at redhat.com
Fri Feb 19 17:41:21 UTC 2016



----- Original Message -----
> 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.
> 

We have hit the same issue in our automated builds for RDO Trunk, and https://bugs.launchpad.net/reno/+bug/1520096 is tracking it for reno.

while it is possible to work around it from the packagers' perspective, it would be better to not assume the source is obtained via a git clone.

Cheers,
Javier

> 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,
> 
> 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