[admin] Document SolidusAdmin intended usage and how to contribute

[elia]

Summary

Checklist

Check out our PR guidelines for more details.

The following are mandatory for all PRs:

• I have written a thorough PR description.
• I have kept my commits small and atomic.
• I have used clear, explanatory commit messages.

The following are not always needed:

• 📖 I have updated the README to account for my changes.
• 📑 I have documented new code with YARD.
• 🛣️ I have opened a PR to update the guides.
• ✅ I have added automated tests to cover my changes.
• 📸 I have attached screenshots to demo visual changes.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (4b46992) 88.56% compared to head (c758304) 88.56%.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5595   +/-   ##
=======================================
  Coverage   88.56%   88.56%           
=======================================
  Files         685      685           
  Lines       16408    16408           
=======================================
  Hits        14531    14531           
  Misses       1877     1877           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[tvdeyen]

What do you think about committing the built tailwind css file into the admin repo (and update it on PR merge)? That file won't change much (at least once the admin has been built out). And even until then it makes sense to have it updated regularly (not just on gem release).

People might use solidus_admin from git source like this

# Gemfile
gem "solidus_admin", github: "solidusio/solidus", branch: "v4.3"

(in order to get bug fixes early for stable versions that have not been released yet.)

We want to make sure they get the admin css file, right?

[tvdeyen]

I have a GH workflow that builds a JS bundle for Alchemy CMS on every merge (and when the source files have changed) https://github.com/AlchemyCMS/alchemy_cms/blob/main/.github/workflows/build.yml

I am happy to contribute this to solidus if we agree on adding the file into the repo

[elia]

@tvdeyen I really didn't want to add such a noisy file, but I admin it might be the easiest thing to do. Do you usually update it manually in Alchemy and then use the GH action as a fallback or you rely on it as the main thing that updates the file?

[tvdeyen]

I really didn't want to add such a noisy file

I won't consider this file noise (at least until the new admin is done). What is the difference to other assets we have committed into our repo?

Do you usually update it manually in Alchemy and then use the GH action as a fallback or you rely on it as the main thing that updates the file?

I manually update the bundle whenever I add a dependency. The GH action is used for automated dependency updates (like dependabot or depfu)

[spaghetticode]

Today we discussed this topic during the core team meeting, and the consensus seems to be to try to avoid directly committing the generated CSS artifact file to this repository. One interesting option that came up is replacing tailwindCSS with https://unocss.dev/, which should remove the issue. I'll try to investigate more on this.

[spaghetticode]

@tvdeyen I'm thinking that regardless of the solution we'll be able to find for the sandbox issue, this PR should be progressed since it includes documentation on many other topics and, speaking of the problematic new admin tailwind.css, it documents the current behavior, which otherwise would remain rather unexposed. We have #5598 for tracking the sandbox issue and exploring its solutions.

[elia]

✅ Leaving a sort of approval for the changes made

[elia]

@tvdeyen I merged giving the above conversation proper space in an issue, after all this documentation accurately describes the current status of things, if we switch to a different approach we'll update it accordingly.

[tvdeyen]

fine for me.