Problem/Motivation

#1945262: Introduce "before" and "after" for conditional ordering in library definitions fixes core libraries so that they no longer depend on individual file weights, but instead on declaring correct dependencies between each other.

The next step is to deprecate weight support in the assets API.

For JavaScript we should be able to just issue a deprecation message and then remove support.

For CSS, 'weight' and 'group' are conflated, see:

LibraryDiscoveryParser.php

foreach ($library[$type] as $category => $files) {
            $category_weight = 'CSS_' . strtoupper($category);
            assert(defined($category_weight), 'Invalid CSS category: ' .        $category . '. See https://www.drupal.org/node/2274843.');
            foreach ($files as $source => $options) {
              if (!isset($options['weight'])) {
                $options['weight'] = 0;
              }
              // Apply the corresponding weight defined by CSS_* constants.
              $options['weight'] += constant($category_weight);
              $library[$type][$source] = $options;

However we can ignore custom weights, keep the current ordering logic otherwise, then open a follow-up to look at either sorting directly on CSS group or doing #1924522: Remove separate CSS_AGGREGATE_THEME aggregate file - the latter would likely remove the group sort completely.
There is also #1924522: Remove separate CSS_AGGREGATE_THEME aggregate file to consider.

Steps to reproduce

While weights are currently respected in core, that is apparently causing more problems than it solves, as weights are being removed from core library definitions, see #3634494: Explicitly setting weight on debounce.js breaks JS load order on Drupal 11.5 for one example.

Proposed resolution

1. Immediately ignore custom weights in the libraries API, so that everything depends on depenencies + before/after.

2. Deprecate custom weights so that people know they should remove them. We have a choice of completely ignoring them in 13.x or throwing an exception. Maybe an assert() would work - doesn't need to be decided here.

3. Remove a handful of remaining weight definitions from core libraries, flushed out by the deprecation.

4. This allows us to completely remove support for the include/exclude style of aggregate URLs, since each aggregate can now be determined accurately via the list of libraries, theme, language, and for CSS, CSS group. This should have a very significant positive effect on aggregate cache hit rates - we're down to 1 URL per combination of files which was always the goal of aggregation changes since 10.1. As a result, the MR removes a net ~600 lines of complex code and test coverage for that case.

Remaining tasks

User interface changes

Introduced terminology

API changes

Data model changes

Release notes snippet

Issue fork drupal-3467488

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

Comments

catch created an issue. See original summary.

Version: 11.x-dev » main

Drupal core is now using the main branch as the primary development branch. New developments and disruptive changes should now be targeted to the main branch.

Read more in the announcement.

catch’s picture

Title: Deprecate support for per-file weight in libraries API » [PP-1] Deprecate support for per-file weight in libraries API
Priority: Normal » Major

We can deprecate per-file weights without resolving the CSS group issue, just won't be able to remove the weight concept entirely from the asset system, but that can be another follow-up once this is done. For example we could sort directly by the CSS group constants rather than converting them to weights.

catch’s picture

Title: [PP-1] Deprecate support for per-file weight in libraries API » Deprecate support for per-file weight in libraries API
catch’s picture

catch’s picture

Title: Deprecate support for per-file weight in libraries API » [PP-x] Deprecate support for per-file weight in libraries API
Status: Active » Postponed

I think we can do the actual deprecation here once we've removed weights in the child issues.

catch’s picture

Title: [PP-x] Deprecate support for per-file weight in libraries API » Deprecate support for per-file weight in libraries API
Status: Postponed » Active
Issue tags: +front end performance, +Performance

In slack, @berdir pointed out that ignoring per-file weights is more likely to work than respecting them these days, because weights override dependencies, but when core or contrib libraries have been updated to remove weights, remaining weights can just end up wrong.

That means we should be able to not only deprecate per-file weights but also ignore them when they're set in a minor release. And that in turn means that we can remove the include/exclude query parameter handling that is currently only a fallback after #3615654: Default to using the 'libraries' parameter for CSS aggregates.

There may or may not be straggling weight definitions in core libraries still but an MR here will help to find any.

berdir’s picture

Yes, specifically negative weights are the problem, blazy/slick for example is completely broken in 11.5 and it will take some work to fix that up. See #3634494: Explicitly setting weight on debounce.js breaks JS load order on Drupal 11.5. I am using our workaround now to ignore all negative weights through an alter hook and haven't noticed any issues yet, but I have not tested/experienced any of the more advanced use cases that the maintainer mentioned required those explicit weights in the past. I'm fairly optimistic that these have been resolved with the reworked dependency based asset ordering.

catch’s picture

Status: Active » Needs work

Made a start:

1. Triggering a deprecation message when we find a custom weight.

2. This flushed out various custom weights still being set around core - removed in the MR but we could spin that off to make the diff more reviewable.

3. Removed support for the include/exclude method of generating aggregate URLs, that allows us to remove a tonne of complexity calculating groups, since we can remove all the split-library detection ($seen_index) which had to be added for bc with custom weights not that long ago.

4. We can also remove sending the aggregate delta in the URL because the files are exactly the same with the same libraries sent, regardless of if another aggregate appears before on some pages or not. This requires one change to the controller logic to filter out non-preprocessed groups when a library contains a mix of aggregated and non-aggregated files.

4. Quite a few tests that were dealing with custom weights just deleted, we still have plenty of coverage for dependencies/before/after.

Things I left for now and could probably be a follow-up:

For CSS, still setting the weight of the files to the 'category weight' then leaving the sort by weight, we could follow up to directly sort on the category weight instead of setting an extra thing but functionally it would be the same, so one less bit of churn to leave that as-is here.

Still running down the test failures so not really ready for review yet.

catch’s picture

Status: Needs work » Needs review

Tests are green.

Main change from #10 is that for CSS, because aggregates are ordered by 'group' (which is the same for JavaScript but different for CSS - there are issues to try to clean that up but we can't do that here), then it's possible for files from the same library to end up in two different aggregates. We can solve that by sending the group in the CSS aggregate URLs and ensuring that aggregate keys are split on group, which will have negligible impact in practice because they usually anyway - the groups are essentially 'module CSS' and 'theme CSS' and theme CSS generally will start with a different category to the last library from the last module that gets loaded so it gets split on that anyway.

Added extra kernel test coverage for this. A small improvement in performance tests just from the refactor without specifically trying to take advantage of it.

smustgrave’s picture

Seems like a large change could we fill in the proposed solution section?

catch’s picture

Issue summary: View changes

Yes good point - fleshed out the issue summary.