SolidusAdmin Journal

Decision Log and Development Notes for SolidusAdmin

This page will keep track of decisions and considerations developed while working on Solidus admin. This is not intended as formal documentation but rather as a way to come back and understand why a direction was taken.

2023-06-08

What kind of extensibility do we want to support?

General Considerations:

• We don't want to end up with "Deface"-like monkey-patching of templates: it's hard to understand where the rendered HTML is coming from if you have a lot of deface overrides changing the same partial.
• We still want to give the maximum flexibility possible.
• We want to allow customizing view logic methods without having to override the whole component
• We want to allow customizing the template without having to touch the view logic of a component
• We want an external API for the component registry in which using DRY.rb or not is an implementation detail
• We need to keep extensibility as the base of our design, and not an afterthought
• No versioning of components, hard to maintain
• Components as a black box

Proposals for helper methods:

• Allow overriding a helper method on an existing component by inheriting from the component
• Keep extensible helper methods in a separate module, and include the module in the components

Extensibility approaches:

• Attempt to strictly control what can be extended, and how (e.g. have preferences for controlling TailwindCSS and import-maps)
  • pro: it's possible to use deprecation cycles
  • con: we have to maintain the preferences and act as a middle-man (see webpacker as a cautionary tale)
• Copy configurations to the host application, and allow them to be modified there, like we do with the starter frontend
  • pro: extreme flexibility and full control for the host application
  • con: extreme flexibility and full control for the host application (things need to be checked manually during upgrades)
• Attempt to provide a starting point and allow the host application to override specific parts, replacing it completely would be a last resort we don't want to encourage nor support
  • pro: we own our side of the configuration while still allowing full flexibility
  • con: we need to be careful about what we declare as supported and what we don't

Decisions:

• Start this wiki-page to keep track of decisions and considerations
• Use markdown documents (similarly to RFCs or Readme-driven-development) to better convey the intent and the reasoning behind a proposal
• When we will face this kind of problem, it's ok to regroup and try to apply the guiding principle together.