FernandoJVideiraandClaude Sonnet 5.5
30cbd9a798
- /help is sent as a few messages (Discord caps an embed at 6000 characters), with a test for the limits - command reference, features, self-hosting, beta and getting-started pages describe the commands; the SQL section is gone - development and contributing: every setting needs a command Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
81 lines
6.2 KiB
Markdown
81 lines
6.2 KiB
Markdown
# Beta features
|
|
|
|
A beta feature is one that is still being tried out, so only chosen people can use it, and only where the server agreed. Two things must both be true:
|
|
|
|
1. **The person is a beta tester**: a member of the beta server who holds the Beta Tester role.
|
|
2. **Beta features are on in the server they use it in**: the beta server itself, or any other server whose owner opted in.
|
|
|
|
The rule is the same on the bot and on the hosted Velox dashboard. The dashboard is proprietary and not part of this repository, so this page is about the bot, and mentions the dashboard only where it explains how the settings get into the database.
|
|
|
|
## Who the testers are
|
|
|
|
- The **beta server** and the **Beta Tester role** are chosen by the bot's owner (the owner of the Discord application) with `/beta set`, in a direct message with the bot. They are stored in the `beta_settings` table, one row. `/beta status` shows them and `/beta off` clears the role, which turns beta features off for everyone.
|
|
- Giving someone the role in Discord makes them a tester. Taking it away removes their access, within about 30 seconds on the bot (a few seconds if the bot has them cached).
|
|
- Until a role is chosen, **nobody** has beta access.
|
|
- Being a tester is about the person, so it is always checked in the **beta server**, also when they use a feature somewhere else. Having a role with the same ID in another server means nothing.
|
|
|
|
## Which servers have beta features
|
|
|
|
- The beta server always has them.
|
|
- Any other server gets them only when its **owner** runs `/config beta-features enabled:true` there. Beta features can act on a whole server (anti-raid behaviour, for example), so the people who answer for the server decide. A server's admins who are not its owner cannot switch it on.
|
|
- The bot's owner can take a server out with `/beta remove-server` (and see them with `/beta servers`), but cannot put one in.
|
|
- The servers are the `beta_guilds` table. The bot polls it every 30 seconds, together with the beta settings.
|
|
|
|
Beta never replaces a feature's own permission checks. A beta command that needs Manage Server still needs it, a music command still needs the DJ role, and anything for the owner or trusted users still needs that.
|
|
|
|
## What a tester sees
|
|
|
|
- **Bot:** beta commands appear only in the beta server and in opted-in servers, and run only for testers. When a server opts in, the commands show up within about 30 seconds. When it opts out, they are removed.
|
|
- **On the hosted Velox dashboard** (proprietary, not in this repository): beta pages and links show a **Beta** badge, only to testers and only for servers where beta features are on.
|
|
|
|
## On the bot
|
|
|
|
Code: `internal/beta` (the rules), `internal/commands/commands.go` (`RegisterBeta`), `internal/bot/bot.go` (`WatchBeta`, `syncBetaCommands`), `internal/commands/betacmd` (`/beta`).
|
|
|
|
- Beta commands are registered in each server where beta features are on, and only there. `/beta` is only in the beta server.
|
|
- Each beta handler is wrapped in `beta.Gate`. It checks that beta is on in the server of the interaction and that the person is a tester, and otherwise answers "This feature is in beta and isn't available to you or this server yet." (Autocomplete requests get an empty list.) Hiding the command is never the only protection.
|
|
- For a person using a command in another server, the bot looks up their roles in the beta server: first in its gateway cache, otherwise it asks Discord (remembered for 30 seconds). If anything fails, the answer is no.
|
|
- If the beta server changes, the beta commands move within 30 seconds. In the beta server, commands this bot left there that no longer exist are removed too. If the beta server is also `GUILD_ID`, the regular commands are kept.
|
|
- `/beta` is registered globally but works only in a direct message with the bot, so it is in no server's menu, and only the owner of the Discord application can use it.
|
|
- The bot remembers the servers where it registered beta commands (`beta_registered` table). A server that opted out while the bot was **offline** is cleaned up on the next start, and a cleanup that fails is retried every 30 seconds. A server the bot has left is forgotten.
|
|
|
|
### Add a beta command
|
|
|
|
Write the command like any other (see the [Development guide](development.md#add-a-simple-command)), but instead of adding it to `AllCommands` and `handlers`, register it from `commands.go`:
|
|
|
|
```go
|
|
func init() {
|
|
RegisterBeta(mything.MyThing, mything.MyThingHandler)
|
|
}
|
|
```
|
|
|
|
`RegisterBeta` adds the definition to `BetaCommands` and the handler, wrapped in `beta.Gate`, to the dispatcher. Buttons and forms that belong to a beta command need the same care: call `beta.Guard(s, i)` at the top of their handlers, because a custom ID can be reached from an old message.
|
|
|
|
### Add beta behaviour that no one runs
|
|
|
|
Event handlers and background jobs have no person to check. Gate them on the server only:
|
|
|
|
```go
|
|
if !beta.ServerEnabled(guildID) {
|
|
return // beta features are off here
|
|
}
|
|
```
|
|
|
|
Do not use this for anything that should only be for testers as people. It means "this server agreed to try beta features", and every member of the server is affected.
|
|
|
|
### Release it
|
|
|
|
Move the definition into `AllCommands` and the handler into the `handlers` map, and delete the `RegisterBeta` call. On the next start the command appears everywhere, and the beta servers drop it from their own lists because it is now a regular command.
|
|
|
|
## On the dashboard
|
|
|
|
The hosted Velox has a proprietary dashboard and API that apply the same rule to their own pages: a beta page is only shown, and its API routes only answer, for a tester in a server where beta features are on. Their code is not part of this repository. If you build your own tool on the same tables, apply the rule on your server side too: never rely on hiding a page.
|
|
|
|
## Why it works this way
|
|
|
|
- The role in Discord is the single list of testers, so there is no second list to keep in step with it.
|
|
- Servers choose to take part, because a beta feature can affect everyone in them.
|
|
- Access is decided on the server, never in the browser.
|
|
- Beta commands do not exist outside the beta server, and the gate checks again when they run.
|
|
- The settings are in the database and changed with commands, not in the environment, so they change without a deploy.
|