API versioning

What the plugin API promises you, what its version means, and how you hear about a change.

The promise

  • A published plugin keeps working. A member you can call stays, with the same signature, until it has been deprecated for at least 90 days.
  • You get a notice before a removal. When a member is deprecated, the owner of every published plugin that uses it gets a notice. The notice says what to use instead and the earliest date the member can go.
  • A call to a removed member raises an error. The error says the member was removed and to rebuild. It stays inside the callback that made the call, and the rest of your plugin keeps running.
  • A plugin never reaches a client too old for it. The listing tells that player to update Bento.

A removed hook and a removed table field do not raise that error. A removed hook stops firing, and your plugin logs a warning when it loads. A removed field on a plain table the API returned reads nil. The 90 days apply to both.

What the version means

The API has one version number, and it moves only when Bento releases a client. A release that changes what a plugin can call raises it by one, and that includes additions. A change to the documentation does not. Marking a member deprecated does not either, because nothing changes for your plugin until the member goes.

Your build states the version it was built against. A client loads a range of versions and refuses a build newer than its own.

The API this site builds against is the one the newest Bento release carries, and it changes when that release ships. A build runs on every client that carries its API version: the release that introduced that version and every release after it. A release that changes nothing a plugin can call keeps the version, so your build also runs on the older clients that carry it.

How you hear

  • In your notices. If your published plugin uses a member that was just deprecated, you get one notice on this site. It names the member, its replacement and the date.
  • In your build result. A build lists the deprecated members it calls, with their replacements and dates. This is advice. The build still publishes.
  • In your editor. The deprecation is in the member's doc comment, so hover shows it.
  • In the reference. A deprecated member has a badge, its date and a link to its replacement.
  • While you test. A plugin running from your plugins folder logs one warning for each deprecated member it calls. Players of a published plugin do not see this.

Notices and build results come from the members your build recorded. A call through an untyped value or a computed name is not recorded, so neither of them can warn you about it. Type your values so that your calls are recorded.

Old plugins and old clients

An old build keeps loading on newer clients. Removing a member does not end support for the builds that used it: the build still loads, and only the call to the removed member fails. A client stops loading an old build only when it can no longer host that version at all.

A client too old for a build does not get it. The person sees the listing and a message to update Bento, the same as for any plugin that needs a newer client.

When the game changes first

The game itself can remove what a member reads, so the member can change or go sooner than 90 days. The same goes for a member that turns out not to be safe to keep.

These are the only changes that skip the 90 days. If one touches your published plugin you still get a notice, and it still shows in the changelog.

Where to see changes

The changelog lists every change, newest first: the version, the date, and what was added, deprecated, removed and changed. The reference always shows the current API.