Constraints on relative asset paths

[jaylett]

The draft spec currently says:

All relative paths MUST be relative to the folder containing the assets-manifest file.

I think this is wrong. I'd expect the asset paths to be relative to (in Django terms) STATIC_ROOT (without staticfiles) or STATICFILES_DIRS[0] (with); that way they can be converted to URLs by either prepending the equivalent of STATIC_URL, or (with Django) by running through a Storage API to generate the URL for us. The only way these are the same is if assets-manifest.json is at the top of that static tree.

However assets-manifest.json should not be in there, for the same reasons that Django currently has deployment issues with ManifestStaticFilesStorage; it should actually be in BASE_DIR so that it's part of a deployment artefact (eg compiled Heroku slug). There's no reason to want to serve the manifest over HTTP, so it shouldn't be in the same file space as generated assets which will be.

I'd like to replace this with some wordier guidance, perhaps something like:

Paths are considered relative to a defined filesystem root, although its location is beyond the scope of this specification and will likely be either configured explicitly in both pipeline and consumer or will take advantage of a convention where the latter is a web framework (for instance, paths might be considered relative to a directory used for automatic serving of static assets by the framework).

I don't think there are compliance issues here (ie no need to use MUST, MAY &c.)

[rbarrois]

Well, the goal of this section is to allow the web framework to find the actual rendered assets. It seems simpler to point the framework to the assets-manifest.json file and have it find all rendered assets directly.

I expect the web framework to have to do some work after reading the assets-manifest.json file; for instance, Django will have to send files to its storage engine, and to generate its own manifest. In that case, Django is interested in finding the rendered assets.

[jaylett]

Yes, but the way Django staticfiles works, it'll copy the assets manifest as well. In development, you'll serve that directory tree directly. Putting the two together seems to me to conflate things unhelpfully.

[rbarrois]

Why would it copy that manifest? The way I see it, external assets will be fetched with a new asset harvester, since we can't require the pipeline to write them within Django's STATIC_ROOT.

Another option would to suggest that users put the manifest outside their outgoing assets folder.

[jaylett]

Here's some concrete details of how I'd want things set up with Django:

• assets go into STATICFILES_DIRS[0], probably os.path.join(BASE_DIR, 'static')
• the manifest should list files relative to that, so it's base.css not static/base.css in asset paths
• collectstatic will sweep everything in that directory up
• but I don't want asset-manifest.json collected; I probably want it directly in BASE_DIR, although where the Django mapper looks for it should be configurable

This isn't compatible with making asset paths relative to the manifest location.

You say:

we can't require the pipeline to write them within Django's STATIC_ROOT.

What the pipeline does should be under control of the developer, surely? (Or, if they choose a pipeline that's inflexible, it's still kind of their call because they chose that pipeline.) I'm not suggesting we require anything; I more want to enable certain amounts of flexibility.

Another option would to suggest that users put the manifest outside their outgoing assets folder.

I think that's a good suggestion. I think when it comes to file system layout, RECOMMENDED and MAY are better than MUST or SHOULD.