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

Thomas Goirand zigo at debian.org
Thu Feb 18 17:17:08 UTC 2016


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'",
html_last_updated_fmt = subprocess.check_output(git_cmd,

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,

Thomas Goirand (zigo)

More information about the OpenStack-dev mailing list