Resolve confusion between `thm` and `git`
Bit of a brain dump on the user experience of thm
and its terminology, based on what I keep trying to do with it while developing the theme. Proposals a tweak to the terminology of its commands to try and make it simpler and just perform the core task.
tl;dr: I think the overlap between managing the themes on a Creek site, (listing them, previewing and publishing a specific theme) and the git
management part (pulling down copies of a theme, pushing changes back) is very confusing. It might be easier if you focus thm
purely on the task of managing themes on the Creek side, and let developers manage files and development themselves, however they see fit.
This doesn't mean Creek shouldn't use git
in the background for managing theme versions, rollbacks, etc. That's all fine. But there's not benefit in exposing that to the developer.
thm
expose functions for managing the active theme on a Creek site only.
Proposal: Have Workflow
- I create a theme in a directory on disk. I manage files however I like, wherever I like. If a developer needs to download the theme, they should clone it from my git/hg/svn repository.
- Themes have a
name
ortitle
defined intheme.json
, to allow sites to have multiple themes or developer new themes. The git (or other) repo name or branch would not have any effect on Creek. - I use
thm
to upload, preview and activate the theme on the Creek site.
In this workflow, you wouldn't need thm download
.
Tasks & Vocabulary
In these examples, thm
would attempt to operate on the site domain specified in theme.json
.
Putting a theme on Creek
-
thm upload [--preview][--activate group-context]
— Upload (orpush
) the theme (creating a new version if supported.)- Providing
--preview
would active the theme forself
, while not creating a permanent new version. - Providing
--activate
would also activate it (see below.)
- Providing
In the backend, Creek may manage this as different branches in a git
repo, subdirectories of a filesystem, or whatever. Doesn't matter.
You may wish to have this command return an identifier for the version created on the Creek side (e.g. 1
, 33
, 642323
if you use directories for versions, the date or time that the upload happens if you don't, or a SHA if you use a Git backend. The utility of this is that the developer could use this identifier in their own git tag …
, so they can cleanly match development repo versions to Creek deploy versions for debugging.
Watching development
-
thm watch
— Watch the theme output directory and automatically upload with--preview
when files change.
You could remove this feature in favour of using another watch
tool in the developer toolchain (e.g. nodemon --watch dist -x "thm upload --preview"
, but there's probably value in providing it for people who want a simple set-up.
Checking site configuration
-
thm list
— lists all themetitle
orname
s stored in Creek for the current domain, plus their current version identifier (if applicable.) -
thm versions [theme-name]
— show a log of versions for the theme stored on Creek -
thm activate [group-context] [theme-name][@version]
— activate a theme stored on Creek, for the specified group.-
self
— Activates the theme for the individual developer only. Akin tothm status edit && thm sync up
. Alternate namesindividual
,me
? -
managers
— Activates the theme for all users in themanagers
group. Akin tothm status publish-managers
-
hosts
— Activates the theme for all users in thehosts
group. Akin tothm status publish-hosts
-
public
— Activates the theme to all visitors of the site. Akin tothm status publish
?thm
should show a warning before doing this, and probably be restricted. Or, just have this functionality built into the web control panel.
-
e.g. $ thm activate managers bff-fm@132
Authentication security & identity
Currently you have a system of generating a user API key on the Creek side and then needing to provide it to thm
to get started. Alternatively, you could allow people to provide their own SSH key to Creek and use this to authenticate them. This way, you could eliminate all of the install
/uninstall
functionality from thm
, and people would just run commands against the domain
specified in theme.json
.
This would eliminate the need for add-key
, get-key
and get-keys
.
This is just a strawman proposal of how focus the tasks thm
performs on what I've needed it to do in starting the work on the BFF theme.