feat: open the repo for community plugin submissions
This commit is contained in:
Lemmy
@@ -6,6 +6,136 @@
|
||||
|
||||
---
|
||||
|
||||
This is where we fetch all the additional plugins for noctalia from.
|
||||
This repo is the **community** plugin source for [Noctalia](https://github.com/noctalia-dev/noctalia-shell). Every
|
||||
plugin merged here is listed in the shell's plugin store and on
|
||||
[noctalia.dev/plugins](https://noctalia.dev/plugins), and users can install it without adding a source of their own.
|
||||
|
||||
WE DO NOT ACCEPT COMMUNITY PLUGINS YET.
|
||||
Plugins maintained by the core team live in
|
||||
[official-plugins](https://github.com/noctalia-dev/official-plugins), which does not accept third-party plugins.
|
||||
This one does. **PRs are welcome.**
|
||||
|
||||
> The plugin system is in **beta**. The manifest format and the plugin API may still change before v5 is stable.
|
||||
> Expect to bump your plugin when they do.
|
||||
|
||||
## Layout
|
||||
|
||||
Each plugin is **one top-level directory**, named after the part of its id that follows the `/`, so `me/hello` lives
|
||||
in `hello/`:
|
||||
|
||||
```
|
||||
hello/
|
||||
plugin.toml # manifest: id ("me/hello"), metadata, entries, settings
|
||||
hello.luau # your entry scripts
|
||||
README.md # rendered as the plugin's page on noctalia.dev
|
||||
thumbnail.webp # the plugin's card image
|
||||
translations/
|
||||
en.json # every label_key / description_key the manifest references
|
||||
```
|
||||
|
||||
`catalog.toml` at the repo root indexes every plugin. **It is generated by CI, so never edit it or include it in a
|
||||
commit.**
|
||||
|
||||
A plugin id is `<author>/<plugin>`. The author part is yours (your GitHub handle is the obvious choice) and keeps your
|
||||
id distinct from everyone else's, but the **directory name is first-come within this repo**. If `weather/` is already
|
||||
taken, pick another name; the official repo is a separate source, so a name used there is not taken here. Both id
|
||||
segments must be lowercase and match `[a-z0-9][a-z0-9._-]*`.
|
||||
|
||||
## What a plugin is allowed to be
|
||||
|
||||
Noctalia plugins are **trusted, unsandboxed Luau**. There is no permission broker and no capability sandbox:
|
||||
installing a plugin is equivalent to running a script the user owns. It can read and write files, spawn processes, and
|
||||
talk to the network as the user.
|
||||
|
||||
That is a deliberate design choice, and it puts the burden on review. So:
|
||||
|
||||
- **No obfuscated, minified, or generated code.** A reviewer must be able to read every line you ship.
|
||||
- **No downloading and executing remote code.** Ship your logic in the repo, at a version people reviewed.
|
||||
- **Declare what you shell out to.** External commands go in `dependencies` in `plugin.toml` and get a mention in your
|
||||
README.
|
||||
- **Account for every network call, filesystem write, and spawned process** in your PR description.
|
||||
|
||||
Anything that looks like it is hiding what it does will be rejected, regardless of intent.
|
||||
|
||||
## Writing a plugin
|
||||
|
||||
The [plugin development docs](https://docs.noctalia.dev/v5/plugins/development/) are the reference: the
|
||||
[manifest](https://docs.noctalia.dev/v5/plugins/development/manifest/), the
|
||||
[entry types](https://docs.noctalia.dev/v5/plugins/development/entries/) (`[[widget]]`, `[[panel]]`, `[[shortcut]]`,
|
||||
`[[service]]`, `[[desktop_widget]]`, `[[launcher_provider]]`), the
|
||||
[declarative UI](https://docs.noctalia.dev/v5/plugins/development/declarative-ui/) vocabulary, the
|
||||
[runtime API](https://docs.noctalia.dev/v5/plugins/development/runtime-api/), and the
|
||||
[workflow](https://docs.noctalia.dev/v5/plugins/development/workflow/) for developing and testing locally.
|
||||
|
||||
The fastest start is to read
|
||||
[`noctalia/example`](https://github.com/noctalia-dev/official-plugins/tree/main/example) in the official repo. It
|
||||
exercises a bar widget, a declarative widget, a service, a shortcut, a launcher provider, and a panel in one plugin.
|
||||
|
||||
To run your plugin while you work on it, add this checkout as a `path` source:
|
||||
|
||||
```sh
|
||||
noctalia msg plugins source add dev path ~/dev/community-plugins
|
||||
noctalia msg plugins enable me/hello
|
||||
```
|
||||
|
||||
`.luau` edits hot-reload; manifest changes are picked up on the next config reload.
|
||||
|
||||
### Editor setup
|
||||
|
||||
`noctalia.d.luau` declares the whole plugin API, so luau-lsp gives you autocomplete and typo diagnostics. It lives in
|
||||
official-plugins, which is its single source of truth; it is **not** vendored here, because a committed copy would be a
|
||||
second one for everyone to trust and keep in sync. Fetch it into the repo root, where it is gitignored:
|
||||
|
||||
```sh
|
||||
curl -O https://raw.githubusercontent.com/noctalia-dev/official-plugins/main/noctalia.d.luau
|
||||
```
|
||||
|
||||
Re-run that whenever the plugin API changes; your local copy is a snapshot, not a subscription.
|
||||
|
||||
The committed `.vscode/settings.json` already points luau-lsp at it; for another editor, add it to luau-lsp's
|
||||
`types.definitionFiles`. `.luaurc` sets `nonstrict` mode, matching the `--!nonstrict` directive every plugin file
|
||||
starts with.
|
||||
|
||||
### Thumbnail
|
||||
|
||||
Every plugin ships a `thumbnail.webp`. It is the card image in the plugin store and on the website. Generate one with
|
||||
the **[thumbnail generator](https://assets.noctalia.dev/plugins/thumbnail-generator.html)**: drop in a screenshot of
|
||||
your plugin, set the title, category tag and accent color, then export the 960×540 WebP and commit it as
|
||||
`<plugin>/thumbnail.webp`.
|
||||
|
||||
### Translations
|
||||
|
||||
Write `translations/en.json` only. Every `label_key` and `description_key` in your manifest must resolve to a key in
|
||||
it, and CI checks this. Do not add machine-translated locales; other languages are handled separately.
|
||||
|
||||
## Submitting
|
||||
|
||||
Open a PR against `main`. CI validates your manifest, entry scripts, required files, and thumbnail on every push.
|
||||
|
||||
- **One plugin per PR.**
|
||||
- The directory name matches the part of `id` after the `/` in `plugin.toml` **exactly**.
|
||||
- `version` is semver and gets bumped on every change to the plugin.
|
||||
- `min_noctalia` is the Noctalia version you actually tested against. Users on older builds are then told the plugin
|
||||
needs an upgrade instead of getting a broken install.
|
||||
- `license` is set in `plugin.toml`. You keep the copyright on your plugin; if it is not MIT, put a `LICENSE` file in
|
||||
your plugin directory. There is no repo-wide license covering contributed plugins.
|
||||
- Screenshots or a short video for anything with a visual surface.
|
||||
|
||||
Maintainers read the code before merging. Expect review comments about clarity, and about anything the plugin does
|
||||
that is not obvious from its description.
|
||||
|
||||
## Maintaining your plugin
|
||||
|
||||
The plugin directory is yours. Someone else's PR changing your plugin is not merged without your sign-off, unless it
|
||||
fixes something that is broken or is a mechanical change applied across the whole repo. Maintainers will @-mention you
|
||||
on PRs and issues that touch it.
|
||||
|
||||
If you stop maintaining a plugin, set `deprecated = true` in its `plugin.toml` rather than deleting the directory. The
|
||||
store keeps working for people who already installed it, but it stops being offered to new users. Plugins that are
|
||||
broken and unmaintained across a Noctalia release may be deprecated by maintainers.
|
||||
|
||||
## Help
|
||||
|
||||
- [Documentation](https://docs.noctalia.dev)
|
||||
- [Discord](https://discord.noctalia.dev)
|
||||
- Bugs in Noctalia itself (not in a plugin) belong in
|
||||
[noctalia](https://github.com/noctalia-dev/noctalia/issues).
|
||||
|
||||
Reference in New Issue
Block a user