Alternative way of sharing spoons

[streetturtle]

I would like to propose an alternative way of sharing spoons.

What I think is missing in the current way of sharing spoons using a mono repo https://github.com/Hammerspoon/Spoons:

• it's not user (beginner) friendly. Instead of showing how to use the spoons, the spoon page is giving a documentation about the internals of the spoon, like methods and variables (example). I believe that this way is perfect for libraries or utility functions.
• no screenshots. I guess it's not possible with lua docs to add screenshots. But most of the spoons provides some kind of visual changes, like menubar apps, window management, notifications, and screenshots would be the great addition to the description of the spoon.

What I propose:
To put each spoon in it's own repository. This gives following benefits:

• Readme in markdown: screenshots, video, code examples, etc.
• Gives visibility of which spoons are popular by being able to star a repo.
• Release management. With a simple gh-action it's possible to setup automated releases. Gh-action generates a .zip with a .spoon inside. Each new version can be simply downloaded from the releases page of the repository.
• Updates. With github releases it's possbile to check if there is a new version of the spoon. Here is an example function.
• Maybe this will simplify life of hammerspoon maintainers? 😄 Spoons will be created by community only, so you don't need to maintain the /spoons repository anymore.

You can find some examples here:

• /gitlab-merge-requests.spoon.
• /spotify-search-and-play.spoon.

[cmsj]

it's definitely the case that this Spoons repo is under-maintained - it's pretty much just me looking at Issues/PRs and I don't do a very good job of even that. I have been thinking recently that it was a mistake to unify them all in one place.

I would still like to have a semi-centralised registry so people can find Spoons, and I do like having a single repo of all their API docs (Hammerspoon doesn't really try to be "beginner" friendly, in the sense that to even be using Hammerspoon, you're supposed to be a programmer and thus likely to be used to navigating API docs), but certainly it wouldn't hurt if the Spoons had more examples of how to use them.

I like the idea of providing a sample repo that people could fork and have all of the build/release mechanics available to them immediately. We could potentially have those Actions open a PR on this repo when a new release happens, to update a registry of Spoons/versions.

Would you be interested in collaborating on coming up with a ready-to-go repo that includes all the gh-action workflows required?

[streetturtle]

Absolutely!

For my spoons I'm using a following template project: /fork-my-spoons/template.spoon with a release action, which is triggered when a new tag is pushed, then it archives the content of repository and creates a new release out of it.

Regarding discoverability of Spoons, I was thinking of having some special topic, like hs-spoon or hammerspoon-spoon, added to the repo. Then all the spoons will end up on the topic's page: https://github.com/topics/hs-spoon. Github also allows to "curate a topic": Curating a new topic or collection

[dbalatero]

My 2 cents: I've found the Spoon management system difficult to use both as a plugin author and a user of Spoons.

This is why my repos tend to give the following advice:

# Just run these 2 commands
mkdir -p ~/.hammerspoon/Spoons
git clone https://github.com/dbalatero/SkyRocket.spoon.git ~/.hammerspoon/Spoons/SkyRocket.spoon

I don't want to introduce any friction between my users seeing my repo page and trying out the plugin.

I really like how something like vim-plug does it, where you pass it the Github URL as username/repo:

Plug 'dbalatero/foo-plugin'

The plugin manager simply does a Git clone of that repo to the plugins directory. Running :PlugUpdate just does a git pull command on each plugin folder. You can also specify which branch or tag you want, if you care to pin to a version. It also allows for easy forking for anyone that needs it.

I would still like to have a semi-centralised registry so people can find Spoons, and I do like having a single repo of all their API docs (Hammerspoon doesn't really try to be "beginner" friendly, in the sense that to even be using Hammerspoon, you're supposed to be a programmer and thus likely to be used to navigating API docs)

If this is the case, I'm curious why the current convention of packaging them as .zip files might be necessary, given programmers are all used to running Git commands?

[devnoname120]

@dbalatero Have you looked into SpoonInstall? It makes it relatively easy to add new spoons.

Example of ~/.hammerspoon/init.lua file:

hs.loadSpoon("SpoonInstall")
spoon.SpoonInstall:andUse("MouseCircle")

I wish you could specify a repo instead of a name. You can modify SpoonInstall.repo to add custom repos but it's awkward.

[dbalatero]

I've tried it and it just felt like it had sharp edges. I think I just don't love the repo layout of "a big repo full of zip files" and a docs.json file. It's awkward to keep up to date, and doesn't feel very ergonomic to use. Maybe the idea is to avoid a git dependency, I'm not sure.

I don't really want to rely on a 3rd party monorepo for repo management either… that feels like it puts extra work on the repo maintainers, and plugin authors are at the mercy of waiting for a PR review (example of that here)

[devnoname120]

@dbalatero Here is what I do for my custom repos:

hs.loadSpoon("SpoonInstall")

spoon.SpoonInstall:asyncInstallSpoonFromZipURL("https://github.com/devnoname120/hammerspoon-auto-mute-on-wake/releases/download/v1.0/AutoMuteOnWake.spoon.zip", function(_, success)
	_ = success and hs.spoons.use('AutoMuteOnWake', {start = true})
end)

I'm not sure whether it can see that the ZIP changed and download it again.

[muescha]

i have also the problem from the description of a spoon or a hs.* module i can not imagine how i can use this.

there are many vert nice spoons available but i don't know it because of the poor spoon description - and some methods of the spoon are just for activating the spoon but not helpful to understand what a spoon do.

for example i was about to build my own window manager - but on half way i found the MiroWindowManager and this was a 100% fit.