Welcome to bamboo.setuptools_version’s documentation!

The aim of this app is simple - to try and provide a single function, callable by any piece of code, that always returns something when asked for a version number

We should use it as an external script pointing at a source dir:

$ from bamboo.setuptools_version import versionlib
$ versionlib.get_version("/my/git/working/dir")
$ "0.2.3"

There is a circular problem when using the hash of a set of files as an ID, in that when we commit our files, the hash changes. But the hash in version.txt is not the hash just created, so we update version.txt with the new hash - which changes the hash

version.txt will only be able to hold the penultimate correct hash id when checked in.

Luckily we do not need to check in the correct hash id in version.txt

We either manually set the version.txt to a manual tag number then commit, (ideal)

or use git-describe for builds in-between tags,

There is not a suitable approach for versions deployed before commit ( ie during active development). I suggest a flag as part of the build command and then forcing date. (consider tag_build, tag_date approach but I prefer idea of all tags coming from same function)

Provides functions to always return something useful as a version number.


do not use this as an import in setup.py


if git working dir has changed, but no commits made (ie indevelopoment return something distinguishing)


short description

1. given a source directory, assume it is .git, assume it is not faulty, get a git-describe and the current branch and return a valid version

2. If it is not a git directory, look for RELEASE_VERSION file that holds a songle line. Use that.

  1. If RELEASE_VERSION and git not exists - throw out a date.

I produced a mini state machinem the flow of which is below .. todo:: provide dot/graphviz ??

flag = "START"
- calls get_gitdescribe(coderoot, flag)
  returns ("NOGITTAG", None) 
          ("YESGITTAG", "1.0.0")
- calls get_versionfile(coderoot, flag)
      returns ("NOTXTFILE", None)
              ("YESTXTFILE", "1.0.0")
      returns ("NOTXTFILE", None)
              ("YESTXTFILE", "0.9.0")
   return datetime
   return txtfile_str
   set version file
   return gittag_str
   compare version file, set if needed
   return gittag_str

Given a dir, return the git describe value for it.

Test assumes no one is git tracking tmp...

>>> get_gitdescribe("/tmp")
('NOGITTAG', None)
>>> get_gitdescribe("non/existent/dir")
('NOGITTAG', None)

retrieve from the code_root, which is assumed to be a git working dir the git describe result

can and should expand to handle a lot of edge cases


Normal case: in a git repo return tag based version

>>> import os, subprocess, shutil
>>> t = "/tmp/foo123"
>>> os.mkdir(t)
>>> junk = subprocess.check_output(["git", "init"], cwd=t)
>>> junk = subprocess.check_output(["touch", "foo"], cwd=t)
>>> junk = subprocess.check_output(["git", "add", "foo"], cwd=t)
>>> junk = subprocess.check_output(["git", "commit", "-m", "'test'"], cwd=t)
>>> junk = subprocess.check_output(["git", "tag", "-a", "0.0.1", "-m", "'test'"], cwd=t)
>>> get_version(t) #normal case
>>> shutil.rmtree(t)

No git directory, look for RELEASE_VERSION

>>> t = "/tmp/foo123"
>>> os.mkdir(t)
>>> open(os.path.join(t, "RELEASE_VERSION"),'w').write("0.0.2-test")
>>> get_version(t) #use txt file
>>> shutil.rmtree(t)

Nothing in dir at all

>>> t = "/tmp/foo123"
>>> os.mkdir(t)
>>> get_version(t) 
>>> shutil.rmtree(t)
We assume a file RELEASE_VERSION always exists next to
setup.py. We always assume that the file holds one line, one string.

return a (flag, string) if file is there and correct, else return (flag, None)

bamboo.setuptools_version.versionlib.write_versionfile(code_root, versionstr)[source]

We have discovered that RELEASE_VERSION either does not exist or has an (different/older) version number. Overwrite RELEASE_VERSION file