packaging recipe {debupstream-base} unrecognized - doc update needed

[Bryce Harrington]

According to https://help.launchpad.net/Packaging/SourceBuilds/Recipes, one of the available variables to use in constructing a snapshot version number is 'debupstream-base':

    https://help.launchpad.net/Packaging/SourceBuilds/Recipes

However, when I construct a recipe using this parameter, it doesn't get substituted:

Retrieving 'lp:pixman' to put at '/home/buildd/build-RECIPEBRANCHBUILD-893374/chroot-autobuild/home/buildd/work/tree/recipe-{debupstream-base}+git{time}.{git-commit}-{revno:packaging}'.
Merging 'lp:~cairo.admin/+junk/pixman-packaging' in to '/home/buildd/build-RECIPEBRANCHBUILD-893374/chroot-autobuild/home/buildd/work/tree/recipe-{debupstream-base}+git{time}.{git-commit}-{revno:packaging}'.
All changes applied successfully.
Committing to: /home/buildd/build-RECIPEBRANCHBUILD-893374/chroot-autobuild/home/buildd/work/tree/recipe-{debupstream-base}+git{time}.{git-commit}-{revno:packaging}/
...
added debian/patches/test-increase-timeout.diff
Committed revision 1957.
bzr: ERROR: bzrlib.errors.BzrCommandError: Invalid deb-version: {debupstream-base}+git201503232309.594e6a6-1958~ubuntu14.10.1: Invalid version string '{debupstream-base}+git201503232309.594e6a6-1958~ubuntu14.10.1'

Traceback (most recent call last):
  File "/usr/lib/python2.7/dist-packages/bzrlib/commands.py", line 930, in exception_to_return_code
    return the_callable(*args, **kwargs)
  File "/usr/lib/python2.7/dist-packages/bzrlib/commands.py", line 1121, in run_bzr
    ret = run(*run_argv)
  File "/usr/lib/python2.7/dist-packages/bzrlib/commands.py", line 673, in run_argv_aliases
    return self.run(**all_cmd_args)
  File "/usr/lib/python2.7/dist-packages/bzrlib/commands.py", line 697, in run
    return self._operation.run_simple(*args, **kwargs)
  File "/usr/lib/python2.7/dist-packages/bzrlib/cleanup.py", line 136, in run_simple
    self.cleanups, self.func, *args, **kwargs)
  File "/usr/lib/python2.7/dist-packages/bzrlib/cleanup.py", line 166, in _do_with_cleanups
    result = func(*args, **kwargs)
  File "/usr/lib/python2.7/dist-packages/bzrlib/plugins/builder/cmds.py", line 376, in run
    append_version=append_version)
  File "/usr/lib/python2.7/dist-packages/bzrlib/plugins/builder/deb_util.py", line 223, in add_autobuild_changelog_entry
    % (version, e))
BzrCommandError: Invalid deb-version: {debupstream-base}+git201503232309.594e6a6-1958~ubuntu14.10.1: Invalid version string '{debupstream-base}+git201503232309.594e6a6-1958~ubuntu14.10.1'

I've been building pixman successfully for some time now, and the *only* change I've done is the new version string.

[Bryce Harrington (bryce)]

I note also lp bug #921251, which was marked invalid but I think may be a related problem, of {latest-tag} not getting substituted.

I'll make a guess that the '-' in the variable name messes things up somehow.

[Bryce Harrington (bryce)]

My guess was wrong! {debupstream} also fails.

Poking around further, I found that with version 0.4, it is required to specify the branch, e.g. {debupstream:packaging}
https://bugs.launchpad.net/launchpad-buildd/+bug/1350430

The documentation does in fact accurately reflect this change:

  debversion, debupstream and debupstream-base require debian/changelog to exist
  in the given branch. In recipe versions 0.3 and earlier, the changelog will be read
  from the final tree if the branch name is omitted.
  https://help.launchpad.net/Packaging/SourceBuilds/Recipes

But I totally glossed over this when I read it. It should be expressed more explicitly:

  debversion, debupstream and debupstream-base require debian/changelog to exist
  in the given branch. For recipe versions 0.4 and newer, you *must* specify the name
  of the branch (e.g. {debupstream-base:packaging}). In recipe versions 0.3 and earlier,
  the changelog will be read from the final tree if the branch name is omitted.

[Colin Watson (cjwatson)]

I've applied your suggested clarification to the documentation. Thanks!