Lua Academy · Lesson

Versioning and Dependency Management

Track plugin versions and check compatibility at load time.

Versioning and Dependency Management is a free Lua Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Lua Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Versioning Matters

Plugins evolve. A plugin v2.0 may be incompatible with v1.0 APIs. Version tracking prevents silent compatibility failures.

Semantic Versioning

Use semantic versioning: MAJOR.MINOR.PATCH. Breaking changes increment MAJOR, new features increment MINOR, bug fixes increment PATCH.

Plugin Manifest with Version

Each plugin declares its own version and required app API version.

return {
  name        = "auth",
  version     = "2.1.0",
  apiRequired = ">=1.0.0",
  deps        = { {name="logger", version=">=1.0.0"} },
  init        = function(app) -- ... end
}

Version Parsing

Parse a version string into comparable components.

local function parseVersion(v)
  local major, minor, patch = v:match("(%d+)%.(%d+)%.(%d+)")
  return {tonumber(major), tonumber(minor), tonumber(patch)}
end
local function versionGe(a, b)
  a, b = parseVersion(a), parseVersion(b)
  for i = 1, 3 do
    if a[i] ~= b[i] then return a[i] > b[i] end
  end
  return true
end

Compatibility Check

On plugin load, verify that the app's API version satisfies the plugin's requirement.

local APP_VERSION = "1.5.0"
local function checkCompatibility(plugin)
  local req = plugin.apiRequired or ">=0.0.0"
  local minVer = req:match(">=(.+)")
  if minVer and not versionGe(APP_VERSION, minVer) then
    error(("Plugin %s requires app >= %s, got %s"):format(
      plugin.name, minVer, APP_VERSION))
  end
end

Dependency Graph Resolution

Build a dependency graph and perform topological sort to determine load order.

Circular Dependency Detection

Track which plugins are in the middle of loading. If a plugin depends on one already being loaded (in a cycle), raise an error.

local loading = {}
local function loadWithCycleCheck(name, plugins)
  if loading[name] then error("Circular dependency: " .. name) end
  loading[name] = true
  -- load deps then load plugin
  loading[name] = nil
end

Upgrade Paths

Document migration guides for MAJOR version bumps. Consider providing a compatibility shim for old plugin APIs during a transition period.

Plugin Registry with Versions

A central registry stores all installed plugin versions. Resolve conflicts by preferring the highest compatible version.

Lockfile Pattern

Like npm's package-lock.json: record the exact versions used in a production deployment to ensure reproducible builds.

Runtime Version Negotiation

Allow plugins to declare multiple compatible API versions. The host app negotiates and picks the highest mutually supported version.

Versioning Question

What does a MAJOR version bump in semantic versioning indicate?

Recap: Versioning and Dependencies

Include version and apiRequired in every plugin manifest. Parse and compare versions at load time. Detect circular dependencies. Use topological sort for load order. Keep a lockfile for reproducible production deployments.

Frequently asked questions

Is the “Versioning and Dependency Management” lesson free?

Yes — the full text of “Versioning and Dependency Management” is free to read here on the web, and the Lua Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Lua Academy course, upgrade to CoddyKit PRO.

What will I learn in “Versioning and Dependency Management”?

Track plugin versions and check compatibility at load time. You practise Lua Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Lua Academy?

No prior experience is required. Lua Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Versioning and Dependency Management” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Lua Academy lesson?

Yes. Every Lua Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Lua Academy