horizon for Ubuntu
------------------

During the Juno/14.10 development cycle, use of xstatic packages was introduced
so that CSS, JS and other static assets did not have to be embedded in the
horizon source tree.

These have been packaged in Debian, however to support continued inclusion of
Horizon in Ubuntu main, and to limit the scope of use of such assets in
Ubuntu main, these assets are bundled up alongside the upstream release tarball
and are included in the python3-django-horizon package under horizon.xstatic.

The xstatic assets are managed as a gbp component tarball using the multi-orig
feature of source format 3.0. This means there are two orig tarballs:

    horizon_<version>.orig.tar.gz           # main upstream source
    horizon_<version>.orig-xstatic.tar.gz   # bundled xstatic assets

The component tarball extracts to ./xstatic/ at the source root. This content
is also committed to the packaging branch so that xstatic files can be patched
with quilt. For example:

    quilt edit ./xstatic/pkg/angular/data/angular-animate.js

Updating for a new upstream release
------------------------------------

The xstatic component is configured as `component = xstatic` in the
[import-orig] section of debian/gbp.conf. gbp import-orig therefore loads the
xstatic tarball automatically when it is found beside the main tarball. Do
not pass --component on the command line: it is already set in gbp.conf, and
repeating it imports the component twice (producing duplicate pristine-tar
entries).

1. Obtain the main upstream tarball in the parent directory:

       ../horizon_<version>.orig.tar.gz

   (e.g. via uscan, which downloads and runs mk-origtargz there).

2. Generate the xstatic component tarball:

       bash debian/bundle-xstatic.sh <version>

   This uses pip to download all xstatic packages listed in requirements.txt
   (constrained by OpenStack upper-constraints) and bundles them into
   ../horizon_<version>.orig-xstatic.tar.gz, next to the main tarball.

3. Import the main tarball and the xstatic component together:

       gbp import-orig --no-interactive --no-merge \
           --upstream-version=<version> \
           ../horizon_<version>.orig.tar.gz

   gbp finds ../horizon_<version>.orig-xstatic.tar.gz beside the main tarball
   (component=xstatic comes from debian/gbp.conf) and imports both in a single
   commit on the upstream branch. It tags <version> and updates pristine-tar
   for both tarballs, folding the xstatic contents into ./xstatic/ in the
   source tree.

4. Merge upstream into the packaging branch using the cloud-archive-utils tools:

       cloud-archive-merge-and-build

5. Update the packaging as needed (refresh patches, update changelog, etc.)

Refreshing xstatic assets only
-------------------------------

If only the xstatic assets need refreshing (e.g. due to a constraint change)
without a new upstream release, regenerate the xstatic tarball, then re-import
the current upstream version. Since import-orig refuses to reuse an existing
tag, first remove that version's tag and reset the upstream and pristine-tar
branches to before its import:

       bash debian/bundle-xstatic.sh <version>
       git tag -d <version>
       git branch -f <upstream-branch> <version>^
       git branch -f pristine-tar <version's pristine-tar commit>^

       gbp import-orig --no-interactive --no-merge \
           --upstream-version=<version> \
           ../horizon_<version>.orig.tar.gz

   <upstream-branch> is the upstream-branch set in debian/gbp.conf. See the git
   log of the upstream and pristine-tar branches to find the commits to reset
   to.
