altf4arnold/datatracker
1
0
Fork 0
Code Issues Pull requests Actions 3 Packages Projects Releases Wiki Activity

Added a static/README file to provide guidance on the new static files setup.

Browse source 
- Legacy-Id: 9887
This commit is contained in:
Henrik Levkowetz 2015-07-26 18:12:59 +00:00
parent 415f42af82
commit a2bd61c29e
1 changed files with 57 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

57
static/README.rst Normal file
View file

@ -0,0 +1,57 @@
Handling of External Javascript and CSS Components
==================================================
This directory (``static/``) holds a number of subdirectories, where one is handled
differently than the rest: the ``lib/`` subdirectory holds distribution files for external
client-side components, currently (18 Apr 2015) this means ``js`` and ``css`` components.
These components each reside in their own subdirectory, which is named with the component
name:
henrik@zinfandel $ ls -l static/lib
total 44
drwxr-xr-x 6 henrik henrik 4096 Jul 25 15:25 bootstrap
drwxr-xr-x 4 henrik henrik 4096 Jul 25 15:25 bootstrap-datepicker
drwxr-xr-x 4 henrik henrik 4096 Jul 25 15:25 font-awesome
drwxr-xr-x 2 henrik henrik 4096 Jul 25 15:25 jquery
drwxr-xr-x 2 henrik henrik 4096 Jul 25 15:25 jquery.cookie
drwxr-xr-x 2 henrik henrik 4096 Jul 25 15:24 ptmono
drwxr-xr-x 2 henrik henrik 4096 Jul 25 15:24 ptsans
drwxr-xr-x 2 henrik henrik 4096 Jul 25 15:24 ptserif
drwxr-xr-x 2 henrik henrik 4096 Jul 25 15:25 select2
drwxr-xr-x 2 henrik henrik 4096 Jul 25 15:25 select2-bootstrap-css
If resources served over a CDN and/or with a high max-age don't have different URLs for
different versions, then any component upgrade which is accompanied by a change in template
functionality will be have a long transition time during which the new pages are served with
old components, with possible breakage. We want to avoid this.
The intention is that after a release has been checked out, but before it is deployed,
the whole static directory should be copied to a location which is accessible under the
URL given by STATIC_URL -- in production mode this URL contains the datatracker release
version, which will let the CDN serve the static files which correspond to the current
release.
With the exception of the ``pt*`` fonts, all components under ``static/lib/`` are managed
through a bower_ file; ``ietf/static/bower.json``. In order to install a new
version of a component, you should update the ``bower.json`` file, and then run the management
command::
$ ietf/manage.py bower_install
That command will fetch the required version of each external component listed in
``bower.json`` (actually, it will do this for *all* ``bower.json`` files found in the
``static/`` directories of all ``INSTALLED_APPS``), saving them temporarily under
``.tmp/bower_components/``; it will then extract the relevant ``js`` and ``css`` files and
place them in an appropriately named directory under ``static/lib/``. The location
used by ``bower_install`` is is controlled by ``COMPONENT_ROOT`` in ``settings.py``.
Any datatracker-specific static files which should be served by the CDN rather than
directly by the datatracker web server should be moved from under ``static/ to ``ietf/static/``,
so that they will be collected by the ``ietf/manage.py collectstatic`` command and
placed under `static/lib/`` from where they will be made available to the CDN. Any
template files referencing the files in question will need to be updated to use the
``{% static 'foo/bar.jpg' %}`` notation to reference the files, so that the correct
static url will be emitted.
.. _bower: http://bower.io/