Update some documentation (and convert to Markdown.)
- Legacy-Id: 19708
This commit is contained in:
Lars Eggert
parent
9e038d3e98
commit
dd59b008b5
27
LICENSE
27
LICENSE
|
|
@ -1,27 +0,0 @@
|
||||||
Copyright (c) 2008,2018, The IETF Trust
|
|
||||||
All rights reserved.
|
|
||||||
|
|
||||||
Redistribution and use in source and binary forms, with or without
|
|
||||||
modification, are permitted provided that the following conditions are met:
|
|
||||||
|
|
||||||
1. Redistributions of source code must retain the above copyright notice,
|
|
||||||
this list of conditions and the following disclaimer.
|
|
||||||
|
|
||||||
2. Redistributions in binary form must reproduce the above copyright
|
|
||||||
notice, this list of conditions and the following disclaimer in the
|
|
||||||
documentation and/or other materials provided with the distribution.
|
|
||||||
|
|
||||||
3. Neither the name of the copyright holder nor the names of its contributors
|
|
||||||
may be used to endorse or promote products derived from this software
|
|
||||||
without specific prior written permission.
|
|
||||||
|
|
||||||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
||||||
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
||||||
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
||||||
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
||||||
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
||||||
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
||||||
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
||||||
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
||||||
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
||||||
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
||||||
27
LICENSE.md
Normal file
27
LICENSE.md
Normal file
|
|
@ -0,0 +1,27 @@
|
||||||
|
Copyright (c) 2008, 2018, The IETF Trust
|
||||||
|
All rights reserved.
|
||||||
|
|
||||||
|
Redistribution and use in source and binary forms, with or without modification,
|
||||||
|
are permitted provided that the following conditions are met:
|
||||||
|
|
||||||
|
1. Redistributions of source code must retain the above copyright notice, this
|
||||||
|
list of conditions and the following disclaimer.
|
||||||
|
|
||||||
|
2. Redistributions in binary form must reproduce the above copyright notice,
|
||||||
|
this list of conditions and the following disclaimer in the documentation
|
||||||
|
and/or other materials provided with the distribution.
|
||||||
|
|
||||||
|
3. Neither the name of the copyright holder nor the names of its contributors
|
||||||
|
may be used to endorse or promote products derived from this software without
|
||||||
|
specific prior written permission.
|
||||||
|
|
||||||
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
||||||
|
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
||||||
|
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||||||
|
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
|
||||||
|
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
||||||
|
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
||||||
|
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
|
||||||
|
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||||
|
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
||||||
|
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||||
183
README-CDN.rst
183
README-CDN.rst
|
|
@ -1,183 +0,0 @@
|
||||||
================================================================================
|
|
||||||
Serving Static Datatracker Files via a CDN
|
|
||||||
================================================================================
|
|
||||||
|
|
||||||
Intro
|
|
||||||
=====
|
|
||||||
|
|
||||||
With release 6.4.0, the way that the static files used by the datatracker are
|
|
||||||
handled changes substantially. Static files were previously versioned under a
|
|
||||||
top-level ``static/`` directory, but this is not the case any more. External
|
|
||||||
files (such as for instance ``jquery.min.js``) are now placed under
|
|
||||||
``ietf/externals/static/`` and updated using a tool called bower_, while
|
|
||||||
datatracker-specific files (images, css, js, etc.) are located under
|
|
||||||
``ietf/static/ietf/`` and ``ietf/secr/static/secr/`` respectively.
|
|
||||||
|
|
||||||
The following sections provide more details about handling of internals,
|
|
||||||
externals, and how deployment is done.
|
|
||||||
|
|
||||||
|
|
||||||
Serving Static Files via CDN
|
|
||||||
============================
|
|
||||||
|
|
||||||
Production Mode
|
|
||||||
---------------
|
|
||||||
|
|
||||||
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 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 standard django 'collectstatic' management command will be
|
|
||||||
run, resulting in all static files being collected from their working
|
|
||||||
directory location and placed in an appropiate location for serving via CDN.
|
|
||||||
This location will have the datatracker release version as part of its URL,
|
|
||||||
so that after the deployment of a new release, the CDN will be forced to fetch
|
|
||||||
the appropriate static files for that release.
|
|
||||||
|
|
||||||
An important part of this is to set up the ``STATIC_ROOT`` and ``STATIC_URL``
|
|
||||||
settings appropriately. In 6.4.0, the setting is as follows in production
|
|
||||||
mode::
|
|
||||||
|
|
||||||
STATIC_URL = "https://www.ietf.org/lib/dt/%s/"%__version__
|
|
||||||
STATIC_ROOT = CDN_ROOT + "/a/www/www6s/lib/dt/%s/"%__version__
|
|
||||||
|
|
||||||
The result is that all static files collected via the ``collectstatic``
|
|
||||||
command will be placed in a location served via CDN, with the release
|
|
||||||
version being part of the URL.
|
|
||||||
|
|
||||||
Development Mode
|
|
||||||
----------------
|
|
||||||
|
|
||||||
In development mode, ``STATIC_URL`` is set to ``/static/``, and Django's
|
|
||||||
``staticfiles`` infrastructure makes the static files available under that
|
|
||||||
local URL root (unless you set
|
|
||||||
``settings.SERVE_CDN_FILES_LOCALLY_IN_DEV_MODE`` to ``False``). It is not
|
|
||||||
necessary to actually populate the ``static/`` directory by running
|
|
||||||
``collectstatic`` in order for static files to be served when running
|
|
||||||
``ietf/manage.py runserver`` -- the ``runserver`` command has extra support
|
|
||||||
for finding and serving static files without running collectstatic.
|
|
||||||
|
|
||||||
In order to work backwards from a file served in development mode to the
|
|
||||||
location from which it is served, the mapping is as follows::
|
|
||||||
|
|
||||||
============================== ==============================
|
|
||||||
Development URL Working copy location
|
|
||||||
============================== ==============================
|
|
||||||
localhost:8000/static/ietf/* ietf/static/ietf/*
|
|
||||||
localhost:8000/static/secr/* ietf/secr/static/secr/*
|
|
||||||
localhost:8000/static/* ietf/externals/static/*
|
|
||||||
============================== ==============================
|
|
||||||
|
|
||||||
Handling of External Javascript and CSS Components
|
|
||||||
==================================================
|
|
||||||
|
|
||||||
In order to make it easy to keep track of and upgrade external components,
|
|
||||||
these are now handled by a tool called ``bower``, via a new management
|
|
||||||
command ``bower_install``. Each external component is listed in a file
|
|
||||||
``ietf/bower.json``. In order to update the version of a component listed in
|
|
||||||
``ietf/bower.json``, or add a new one, you should edit ``bower.json``, and
|
|
||||||
then run the management command::
|
|
||||||
|
|
||||||
$ ietf/manage.py bower_install
|
|
||||||
|
|
||||||
(Not surprisingly, you need to have bower_ installed in order to use this
|
|
||||||
management command.)
|
|
||||||
|
|
||||||
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`` and the
|
|
||||||
directories in ``settings.STATICFILES_DIRS``), saving them temporarily under
|
|
||||||
``.tmp/bower_components/``; it will then extract the relevant production
|
|
||||||
``js`` and ``css`` files and place them in an appropriately named directory
|
|
||||||
under ``ietf/externals/static/``. The latter location is taken from
|
|
||||||
``COMPONENT_ROOT`` in ``settings.py``.
|
|
||||||
|
|
||||||
Managing external components via bower has the additional benefit of
|
|
||||||
managing dependencies -- components that have dependencies will pull in
|
|
||||||
these, so that they also are placed under ``ietf/externals/static/``.
|
|
||||||
You still have to manually add the necessary stylesheet and/or javascript
|
|
||||||
references to your templates, though.
|
|
||||||
|
|
||||||
The ``bower_install`` command is not run automatically by ``bin/mkrelease``,
|
|
||||||
since it needs an updated ``bower.json`` in order to do anything interesting.
|
|
||||||
So when you're intending to update an external web asset to a newer version,
|
|
||||||
you need to edit the ``bower.json`` file, run ``manage.py bower_install``,
|
|
||||||
verify that the new version doesn't break things, and then commit the new
|
|
||||||
files under ``ietf/externals/static/`` and the updated ``bower.json``.
|
|
||||||
|
|
||||||
.. _bower: http://bower.io/
|
|
||||||
|
|
||||||
The ``ietf/externals/static/`` Directory
|
|
||||||
-----------------------------------------
|
|
||||||
|
|
||||||
The directory ``ietf/externals/static/`` holds a number of subdirectories
|
|
||||||
which hold distribution files for external client-side components, collected
|
|
||||||
by ``bower_install`` as described above. Currently
|
|
||||||
(01 Aug 2015) this means ``js`` and ``css`` components and fonts.
|
|
||||||
|
|
||||||
These components each reside in their own subdirectory, which is named with
|
|
||||||
the component name::
|
|
||||||
|
|
||||||
henrik@zinfandel $ ls -l ietf/externals/static/
|
|
||||||
total 40
|
|
||||||
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
|
|
||||||
|
|
||||||
The ``pt*`` fonts are an exception, in that there is no bower component
|
|
||||||
available for these fonts, so they have been put in place manually.
|
|
||||||
|
|
||||||
|
|
||||||
Handling of Internal Static Files
|
|
||||||
=================================
|
|
||||||
|
|
||||||
Previous to this release, internal static files were located under
|
|
||||||
``static/``, mixed together with the external components. They are now
|
|
||||||
located under ``ietf/static/ietf/`` and ``ietf/secr/static/secr``, and will be
|
|
||||||
collected for serving via CDN by the ``collectstatic`` command. Any static
|
|
||||||
files associated with a particular app will be handled the same way (which
|
|
||||||
means that all ``admin/`` static files automatically will be handled correctly, too).
|
|
||||||
|
|
||||||
Handling of Customised Bootstrap Files
|
|
||||||
======================================
|
|
||||||
|
|
||||||
We are using a customised version of Bootstrap_, which is handled specially,
|
|
||||||
by a SVN externals definition in ``ietf/static/ietf``. That pulls the content
|
|
||||||
of the ``bootstrap/dist/`` directory (which is generated by running ``grunt``
|
|
||||||
in the ``bootstrap/`` directory) into ``ietf/static/ietf/bootstrap``, from
|
|
||||||
where it is collected by ``collectstatic``.
|
|
||||||
|
|
||||||
Changes to Template Files
|
|
||||||
=========================
|
|
||||||
|
|
||||||
In order to make the template files refer to the correct versioned CDN URL
|
|
||||||
(as given by the STATIC_URL root) all references to static files in the
|
|
||||||
templates have been updated to use the ``static`` template tag when referring
|
|
||||||
to static files. This will automatically result in both serving static files
|
|
||||||
from the right place in development mode, and referring to the correct
|
|
||||||
versioned URL in production mode and the simpler ``/static/`` urls in
|
|
||||||
development mode.
|
|
||||||
|
|
||||||
.. _bootstrap: http://getbootstrap.com/
|
|
||||||
|
|
||||||
Deployment
|
|
||||||
==========
|
|
||||||
|
|
||||||
During deployment, it is now necessary to run the management command::
|
|
||||||
|
|
||||||
$ ietf/manage.py collectstatic
|
|
||||||
|
|
||||||
before activating a new release.
|
|
||||||
|
|
||||||
The deployment ``README`` file at ``/a/www/ietf-datatracker/README`` has been
|
|
||||||
updated accordingly.
|
|
||||||
|
|
@ -1,35 +0,0 @@
|
||||||
The "new" datatracker uses Twitter Bootstrap for the UI.
|
|
||||||
|
|
||||||
Get familiar with http://getbootstrap.com/getting-started/ and use those
|
|
||||||
UI elements instead of cooking up your own.
|
|
||||||
|
|
||||||
We have some site-wide customization applied to the bootstrap version we keep
|
|
||||||
in bootstrap/ (from which the minified dist version is built); it modifies
|
|
||||||
some stuff under less/
|
|
||||||
|
|
||||||
We also apply some additional customizations in static/css/ietf.css; we
|
|
||||||
should eventually move that under bootstrap/less/ if possible. (ietf.css was
|
|
||||||
what Lars used initially for customization with an unmodified bootstrap.)
|
|
||||||
|
|
||||||
Some ground rules:
|
|
||||||
|
|
||||||
* Think hard before tweaking the bootstrap CSS, it will make it harder to
|
|
||||||
upgrade to future releases.
|
|
||||||
|
|
||||||
* No <style> tags in the HTML! Put CSS into the "morecss" block of a
|
|
||||||
template instead.
|
|
||||||
|
|
||||||
* CSS that is used by multiple templates goes into static/css/ietf.css.
|
|
||||||
|
|
||||||
* Javascript that is only used on one template goes into the "js" block of
|
|
||||||
that template.
|
|
||||||
|
|
||||||
* Javascript that is used by multiple templates goes into static/js/ietf.js.
|
|
||||||
|
|
||||||
* Every template includes jquery, so write jquery code and not plain Javascript.
|
|
||||||
It's shorter and often faster.
|
|
||||||
|
|
||||||
* No CSS, HTML styling or Javascript in the python code!
|
|
||||||
|
|
||||||
* Templates that use jquery or bootstrap plugins include the css file in the
|
|
||||||
"pagehead" block, and the Javascript in the "js" block.
|
|
||||||
130
README.md
Normal file
130
README.md
Normal file
|
|
@ -0,0 +1,130 @@
|
||||||
|
# IETF Datatracker
|
||||||
|
|
||||||
|
## Intro
|
||||||
|
|
||||||
|
We now use `npm` to manage assets for the Datatracker, and `parcel` to
|
||||||
|
package them. `npm` maintains its `node` packages under `node_modules`.
|
||||||
|
|
||||||
|
The Datatracker includes these packages from the various Javascript and
|
||||||
|
CSS files in `ietf/static/js` and `ietf/static/css`, respectively.
|
||||||
|
Static images are likewise in `ietf/static/images`.
|
||||||
|
|
||||||
|
Whenever changes are made to the files under `ietf/static`, you must
|
||||||
|
re-run `parcel` to package them:
|
||||||
|
|
||||||
|
``` shell
|
||||||
|
npx parcel build
|
||||||
|
```
|
||||||
|
|
||||||
|
This will create packages under `ietf/static/dist/ietf`, which are then
|
||||||
|
served by the Django development server, and which must be uploaded to
|
||||||
|
the CDN.
|
||||||
|
|
||||||
|
## Use Bootstrap Whenever You Can
|
||||||
|
|
||||||
|
The "new" datatracker uses Twitter Bootstrap for the UI.
|
||||||
|
|
||||||
|
Get familiar with <https://getbootstrap.com/getting-started/> and use
|
||||||
|
those UI elements, CSS classes, etc. instead of cooking up your own.
|
||||||
|
|
||||||
|
Some ground rules:
|
||||||
|
|
||||||
|
- Think hard before tweaking the bootstrap CSS, it will make it harder
|
||||||
|
to upgrade to future releases.
|
||||||
|
- No `<style>` tags in the HTML! Put CSS into the "morecss" block of
|
||||||
|
a template instead.
|
||||||
|
- CSS that is used by multiple templates goes into static/css/ietf.css
|
||||||
|
or a new CSS file.
|
||||||
|
- Javascript that is only used on one template goes into the "js"
|
||||||
|
block of that template.
|
||||||
|
- Javascript that is used by multiple templates goes into
|
||||||
|
static/js/ietf.js or a new js file.
|
||||||
|
- Every template includes jquery, so write jquery code and not plain
|
||||||
|
Javascript. It's shorter and often faster.
|
||||||
|
- Avoid CSS, HTML styling or Javascript in the python code!
|
||||||
|
|
||||||
|
## Serving Static Files via CDN
|
||||||
|
|
||||||
|
### Production Mode
|
||||||
|
|
||||||
|
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 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 standard django `collectstatic` management command
|
||||||
|
will be run, resulting in all static files being collected from their
|
||||||
|
working directory location and placed in an appropriate location for
|
||||||
|
serving via CDN. This location will have the datatracker release version
|
||||||
|
as part of its URL, so that after the deployment of a new release, the
|
||||||
|
CDN will be forced to fetch the appropriate static files for that
|
||||||
|
release.
|
||||||
|
|
||||||
|
An important part of this is to set up the `STATIC_ROOT` and
|
||||||
|
`STATIC_URL` settings appropriately. In 6.4.0, the setting is as follows
|
||||||
|
in production mode:
|
||||||
|
|
||||||
|
```
|
||||||
|
STATIC_URL = "https://www.ietf.org/lib/dt/%s/"%__version__
|
||||||
|
STATIC_ROOT = CDN_ROOT + "/a/www/www6s/lib/dt/%s/"%__version__
|
||||||
|
```
|
||||||
|
|
||||||
|
The result is that all static files collected via the `collectstatic`
|
||||||
|
command will be placed in a location served via CDN, with the release
|
||||||
|
version being part of the URL.
|
||||||
|
|
||||||
|
### Development Mode
|
||||||
|
|
||||||
|
In development mode, `STATIC_URL` is set to `/static/`, and Django's
|
||||||
|
`staticfiles` infrastructure makes the static files available under that
|
||||||
|
local URL root (unless you set
|
||||||
|
`settings.SERVE_CDN_FILES_LOCALLY_IN_DEV_MODE` to `False`). It is not
|
||||||
|
necessary to actually populate the `static/` directory by running
|
||||||
|
`collectstatic` in order for static files to be served when running
|
||||||
|
`ietf/manage.py runserver` -- the `runserver` command has extra support
|
||||||
|
for finding and serving static files without running collectstatic.
|
||||||
|
|
||||||
|
In order to work backwards from a file served in development mode to the
|
||||||
|
location from which it is served, the mapping is as follows:
|
||||||
|
|
||||||
|
| Development URL | Working copy location |
|
||||||
|
| --------------- | --------------------- |
|
||||||
|
| localhost:8000/static/ietf/* | ietf/static/ietf/* |
|
||||||
|
| localhost:8000/static/secr/* | ietf/secr/static/secr/*|
|
||||||
|
|
||||||
|
## Handling of External Javascript and CSS Components
|
||||||
|
|
||||||
|
In order to make it easy to keep track of and upgrade external
|
||||||
|
components, these are now handled by a tool called `npm` via the
|
||||||
|
configuration in `package.json`.
|
||||||
|
|
||||||
|
## Handling of Internal Static Files
|
||||||
|
|
||||||
|
Previous to this release, internal static files were located under
|
||||||
|
`static/`, mixed together with the external components. They are now
|
||||||
|
located under `ietf/static/ietf/` and `ietf/secr/static/secr`, and will
|
||||||
|
be collected for serving via CDN by the `collectstatic` command. Any
|
||||||
|
static files associated with a particular app will be handled the same
|
||||||
|
way (which means that all `admin/` static files automatically will be
|
||||||
|
handled correctly, too).
|
||||||
|
|
||||||
|
## Changes to Template Files
|
||||||
|
|
||||||
|
In order to make the template files refer to the correct versioned CDN
|
||||||
|
URL (as given by the STATIC_URL root) all references to static files in
|
||||||
|
the templates have been updated to use the `static` template tag when
|
||||||
|
referring to static files. This will automatically result in both
|
||||||
|
serving static files from the right place in development mode, and
|
||||||
|
referring to the correct versioned URL in production mode and the
|
||||||
|
simpler `/static/` URLs in development mode.
|
||||||
|
|
||||||
|
## Deployment
|
||||||
|
|
||||||
|
During deployment, it is now necessary to run the management command:
|
||||||
|
|
||||||
|
``` shell
|
||||||
|
ietf/manage.py collectstatic
|
||||||
|
````
|
||||||
|
before activating a new release.
|
||||||
Loading…
Reference in a new issue