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