Vuka

Appearance

Compatibility Promise ​

Introduction ​

vuka makes Go's promise: an app that builds and passes its tests on v2.x keeps doing so on every later v2 release — after go get of the new version, with no edits. This page says what that covers, what a minor or patch release may still change, and how the rare change that has to break something is handled.

Which Modules It Covers ​

The promise holds from v2.0.0 for the v2 module set — github.com/vuka-lang/vuka/v2, github.com/vuka-lang/ui/v2, github.com/vuka-lang/web/v2, the vuka command (github.com/vuka-lang/vuka/cmd/vuka/v2) and vukavet (github.com/vuka-lang/vuka/cmd/vukavet/v2) — and for github.com/vuka-lang/orm/v2. How versions are numbered and how an app moves between them is in Versions.

NOTE

v1.0.0 to v1.5.0 kept the same promise within v1. 1.x receives no further releases: no fixes, security fixes included. A 1.x app keeps building on the versions it requires, and moves to 2.0 by hand, as the v2.0.0 release notes describe.

What Is Covered ​

Within v2, a minor or patch release changes nothing here in a way that breaks a working app:

  • The Go API of vuka, ui, web and orm: every exported name of their packages other than internal ones, with its signature and documented behaviour. Plain Go is the language; this is what an app written in Go calls, and what the code vuka generates calls.
  • The .vuka language: its syntax — ?, match, enums, overloading, statics, decorators and attributes — and what each built-in decorator and attribute means.
  • The .vuka.html template language: the package clause and imports, a file's templates and func headers, Go statements in markup, holes, attributes (class:x, {attrs...}, bind:value, style:prop), events, component tags and slots, and a template's <script lang="ts"> and <style scoped>.
  • The browser API pages and islands use: live.*, useVuka(), VukaLink, window.vuka, and the props an island receives.
  • The vuka command: its subcommands, their flags and arguments, the environment variables it reads, its exit statuses, and the files it reads and writes in an app (build/, .vuka/). The same holds for vukavet's checks and flags.
  • Diagnostic codes. A code keeps its meaning: E0401 is a route declared twice in every v2 release. An error's code doesn't turn into a warning's or the reverse, and a code is never reused for something else.
  • The generated-code contract. What vuka gen, vuka eject and go tool vuka build-islands write calls the public API only, so it keeps building against every later v2 of the libraries; an ejected app is plain Go under the same promise as code you wrote. Code generated by an older v2 command builds with a newer v2 library.

What a Release May Change ​

A patch release (v2.1.1) fixes bugs, closes security holes and improves messages. It adds no API.

A minor release (v2.2.0) adds: new API, new decorators and attributes, new subcommands and flags, new diagnostics — including new vuka vet and vukavet warnings, which a build doesn't fail on — and new tooling fixers. It may also:

  • deprecate a name, under the policy below;
  • make something faster or use less memory, and change what the generated code looks like inside while it keeps the contract;
  • raise the minimum Go version to a Go release that is still supported, and the minimum Node.js or Vite version the frontend toolchain needs, said in the release note;
  • improve a diagnostic's wording, its place or its help; match its code, not its text, in a test.

Neither may remove or rename what the promise covers, change a signature, or change documented behaviour a correct program relies on.

The Exceptions ​

As with Go, a release may break an app when not doing so would be worse, and its note says so with what to do:

  • Security. A fix for a security problem may need to break code that relies on the unsafe behaviour.
  • Bugs. Behaviour that contradicts the documentation, or that no correct program relies on, is fixed — a check that should have refused a mistake and didn't, say.
  • Unspecified behaviour. What the documentation leaves open — map and hash ordering, the exact HTML whitespace a template writes, timing — may change.

Deprecation ​

A name, attribute, flag or form that has a better replacement is deprecated, never removed within v2:

  1. It keeps working for at least one minor release after the release that deprecates it — and, since removing it would break the promise, until the next major version.
  2. It is marked: // Deprecated: use X in Go, @deprecated("use X") in .vuka. vuka vet and vukavet warn where it is used, and the warning names the replacement.
  3. The release notes describe the source changes required by a new major version.
  4. The release note says what is deprecated, with a before/after example.

Major Versions ​

A breaking change waits for a major version. A major version is a new module path — v2.0.0 moved the set to github.com/vuka-lang/web/v2 and the others — so apps on the previous one keep building, and every breaking change it makes ships with:

  • documented source changes, including the import paths;
  • a release-note example of the code before and after.

v2.0.0's are in its release notes.

What Is Not Covered ​

The promise leaves these out:

  • internal packages of any module, vuka's toolchain packages, and anything documented as for the compiler's use only.
  • The private shape of generated code. Beyond the contract above — public API only, building against later v2 libraries — the names of generated helpers, how files are split and named (x_html.go, vuka_calls_gen.go, *_gen.go speed-ups), line directives and layout may change. Read generated code; don't import or patch it. Re-run vuka gen after an upgrade.
  • Experimental features: flags, subcommands and environment variables documented as experimental or for debugging (VUKA_LIVE_WHOLE, for one).
  • The live wire protocol between a page's runtime.js and its server, and the islands loader's manifest. Both ends come from one set, and they are compatible within one version only: after a deploy, a page loaded from the old version reloads rather than talking to the new server.
  • The development toolbar, vuka run -watch's output, and the formatting of other terminal output beyond diagnostic codes.
  • Rendered internals: attributes the runtime writes for itself, such as an island host's data-vk-s; select islands by your own id or data-testid.
  • The editor extensions. The VS Code extension has its own version; vuka lsp follows the command's promise for its flags only.

Released under the MIT License. Vuka builds on Go and its tools, which are made by the Go Authors. Vuka is not affiliated with Google or the Go project. Go is a trademark of Google LLC.