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

1. Import the main upstream tarball:

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

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.

3. Import the xstatic component tarball via gbp:

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

   This updates the upstream branch, pristine-tar, and extracts 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, run steps 2 and 3 above with the current
upstream version.
