Call for simplification of Plone 5 Resource Registry

hvelarde · January 6, 2017, 6:52pm

Continuing the discussion from Again, bad out-of-the-box experience with Plone 5:

well, I've been considering this for a while; feel free to criticize and improve.

github.com/plone/Products.CMFPlone

PLIP: Simplify the Resource Registry

opened 04:12PM - 06 Jan 17 UTC

closed 06:46PM - 08 Feb 17 UTC

hvelarde

31 needs: help 32 needs: review 24 status: ready 03 type: feature (plip) 99 tag: resource registry

# PLIP: Simplify the Resource Registry ## Responsible Persons ### Proposer…: @hvelarde ### Seconder: ## Abstract Plone 5 modernized the CSS and JS development experience by incorporating tools like [Bower](https://bower.io/), [Grunt](http://gruntjs.com/), [RequireJS](http://www.requirejs.org/) and [LESS](http://lesscss.org/) into it. In Plone 5, CSS and JS resources for core Plone and add-on packages are managed in a new and completely rewritten Resource Registry that has proven buggy, difficult to maintain, and hard to understand for integrators and non-core developers. We need to change that story by simplifying it. ## Motivation While the motivation of the rewritten was very well justified, the final implementation has shown some problems that we need to address ASAP: * The revolutionary approach chosen (rewrite everything) has proven buggy and difficult to maintain, as the [many issues reported](https://github.com/plone/Products.CMFPlone/issues?q=is%3Aopen+is%3Aissue+label%3A%2299+tag%3A+resource+registry%22) over the last months seem to prove * Some of the JavaScript tools used (Bower, Grunt, RequireJS…) seem to be less attractive nowadays than more modern options ([Webpack](https://webpack.github.io/)…) * Resource bundling was a workaround for a limitation of the HTTP/1.1 protocol and not a CMS feature; [HTTP/2 makes it unnecessary and even undesirable](http://stackoverflow.com/a/30864259/644075) * LESS variable control panel configlet is useless in the context of the resource registry (#1677) Some of these issues have discouraged integrators and add-on developers on using Plone 5. ## Assumptions Plone Framework Team has to discuss around the current toolset, and make a recommendation on its extended usage or its deprecation in favor of more modern options. That could be difficult, given the [current state of JS develoopment](https://community.plone.org/t/i-refuse-to-be-part-of-the-javascript-madness/2825?u=hvelarde). ## Proposal & Implementation The proposal is to completely remove the bundling feature from the Plone core backend (probably including all the recently created `++production++` and `++unique++` namespaces) and UI (configlet). The final result should be something like this: * Plone core should enforce a standardized JS dependency management (currently, by using RequireJS) * Plone should recommend integrators and add-on developers to follow embrace this, but should not enforce them to use it; the only supported mechanism should remain the one selected by the framework team and it should be very clear that integrators and add-on developers would be at their own if they fail to follow this recommendation * Plone should provide bundled core CSS and JS resources for authenticated and anonymous users only and should not try to bundle third party resources in any way * integrators and add-on developers are not enforce to bind resources on any way; that should be their choice * Plone should render references to resources in the order they were registered in the registry * Resource references could be rendered in development or production mode: development mode should render a reference to their name unchanged; production mode should render a reference using a hash (based on last time of cooking) instead, to avoid issues with intermediate proxy servers * Registration of third party CSS and JS resources must fire automatically a cooking process to calculate the hash to be used in production mode * Site managers and administrators must be able to cook production hashes also using an option in the configlet * There should be a way to manually register new CSS/JS resources in the UI of the new refactored resource registry available to administrators only The following example shows how this could work in practice: * A user visits a Plone site as anonymous; the browser will make 2 requests to get the resources: one for CSS, another for JS * The user logs in; the browser will make 2 additional requests to get the resources for logged-in users: one for CSS, another for JS (4 in total) * The user installs a new add-on that includes bundled CSS and JS resources; the browser will make 2 additional requests to get those resources: one for CSS, another for JS (6 in total for authenticated users, 4 in total for anonymous users) * The user installs another add-on that includes 2 new unbundled JS resources; the browser will make 2 additional requests to get those new resources (8 in total for authenticated users, 6 in total for anonymous users) * so on… * For the sake of simplicity, this example is not taking into account other resources that must require request also, like background images referenced in CSS files From the add-on developer point of view this is how this should work: * An add-on developer are recommended to use standardized JS dependency management (currently, by using RequireJS), but are free not to follow this recommendation or not * Add-on developers and integrators must be aware that failing to comply with the previous recommendation is not supported and they will be on their own in case of issues * Static resources should be available using the standard `++resource++` namespace * Add on developers are totally responsible of taking care of the quality of their CSS and JS resources (combination, minification, etc.), the same way they are responsible for other static resources like images * Resource registration/removal is simply an operation over the Plone registry using simplified version of the current record entry removing all unnecessary (current syntax should be available for backwards compatibility until Plone 6 is available) * Add-on developers must have a way to cook their resources after an upgrade This reflects more or less the current situation on Plone 4 on that aspect. ## Deliverables * A new, updated and simplified Resource Registry backend without the needless bundling feature * A new, updated and simplified Resource Registry configlet without the needless bundling feature * An upgrade step to transform resources already registered into the new format; this should include the plone, plone-legacy and plone logged-in bundles * Updated documentation on how developers must install, test and uninstall CSS and JS resources * Updated documentation on how developers should handle JS dependencies (RequireJS or similar) * Documentation on how developers can use the selected resource bundler (Webpack or similar) * Documentation on how resource overriden should be done ## Risks Just another change on the way we do things could discourage core and add-on developers, unless we convince them this time will be different and life is going to be easier for them. The Plone legacy bundle must be removed and a upgrade step must be created to deal with resources already there. Third party resources bundled in the plone and plone logged-in bundles must be decoupled from there. What to do with the other existing bundles in Plone 5 (resourceregistry, thememapper…)? Do they still make sense? Probably just in the context of Plone core. Do we need to be able to manage more bundles in the resource registry UI? I don't know. Currently [there is no way to manage conditions per resource](https://community.plone.org/t/ordering-resources-in-a-bundle/2363?u=hvelarde), do we want that back? What about the overrides? This PLIP is complex and has many obscure aspects that will be evident only after the work is started. ## Participants * Rodrigo Ferreira de Souza (@rodfersou) * Your name here!