Release policy

Semantic versioning

Turian follows semantic versioning (major.minor.patch — for example v1.9.0).

  • Major increments mean breaking changes — your project may need manual updates.
  • Minor increments add features, but existing code continues to compile without changes.
  • Patch increments ship bug fixes and performance improvements with no API changes.

We do not believe in keeping the major version at 0 indefinitely. Turian has been at v1.x.x since v1.0.0, when it became possible to create a game from scratch and build it into a standalone executable. "Production-ready" will be a project decision and announcement, never a version number.

Major releases are technical, not marketing

In most engines a new major version is an event: years of features bundled behind a single number, announced at a keynote, followed by a long and risky migration. Turian takes the version number literally instead. A major release means exactly one thing — something changed in a way that can break existing projects — and it ships the same day as any other release, sometimes carrying a single breaking change and nothing else.

What you can rely on:

  • Every major release has a matching entry in the migration guides telling you exactly what changed and what (if anything) you must do.
  • Breaking data-format changes come with a migration path, not just a changelog line: old files keep loading (with a warning), or a turian-cli command converts a whole project in one go.
  • Because breaking changes are released as they land instead of being saved up for a "big" version, each migration is small and reviewable on its own.

The "what's new in Turian" story lives elsewhere: periodic roundup posts on the blog summarize features and fixes across many releases, independent of version numbers.

Release frequency

We ship a new release every day (when there is a code change). This means bug fixes and features reach you the day they are merged, instead of sitting in a queue for months waiting for the next "big" release.

The advantages of high-frequency releases:

  • A bug you report today is fixed in a release tomorrow — no waiting for a quarterly milestone.
  • Regression hunting is easier because the diff between consecutive releases is small.
  • You can always pin to a specific version and upgrade at your own pace.

We may reduce the frequency in the future once the project stabilises, but the philosophy will remain: ship early, ship often.

Long-term support

We do not offer long-term support (LTS) releases. The project is in its infancy and the API is evolving rapidly. Maintaining an LTS branch would slow development and fragment the community. The best way to stay on a supported version is to follow the latest release.

Multiple versions installed

The zip archives are relocatable: each release extracts to its own folder, and each turian-cli and turian-studio uses the engine libraries in the lib/ folder next to it. Multiple versions can coexist on the same machine, and a project is always compiled against the version you invoked:

~/turian/1.0.0/turian-cli export mygame   # built with 1.0.0
~/turian/1.1.0/turian-cli export mygame   # built with 1.1.0

The Windows installer and the Debian packages install one version system-wide; use the zip archives when you need several side by side. See the Install page.

Guinevere control stylesheet migration

The Excalibur stylesheet API requires callers to be recompiled for the next major release. Replace slider, progress bar and splitter color/radius arguments with .pss declarations, and pass classes or id to select controls. Target slider parts with slider > track, slider > fill and slider > thumb, progress fills with progress > fill, and divider axes with splitter:horizontal or splitter:vertical.

Leave Slider.fontSize, ProgressBar.height and Splitter.thickness omitted to use stylesheet defaults, or supply explicit sizes to override them. These arguments are nullable; code that binds method signatures must use float?. Use named filePath and lineNumber arguments when passing call-site identities. The bundled default stylesheet is installed automatically below application sheets.

Guinevere automatic identity migration

Recompile consumers of TextInput, PasswordInput, TextArea, NumberField, Form, FormField and FormFieldEditor for their compiler-supplied caller parameters. Ordinary direct calls continue to compile; use forwarding lambdas for delegates that require the previous exact method signature. Forms and field renderers accept omitted IDs, while custom property drawers retain their string ID contract. These callable-signature changes belong to the next Guinevere major release.

Treat automatically generated node strings as opaque GUI-session identifiers. Use explicit names for external script references. Duplicate explicit sibling IDs now throw; supply distinct names or wrap collection items in using var identity = gui.ItemKey(item.Id) in both passes. Choose stable immutable typed item keys to keep edit state, focus and pointer capture through reorder. A keyed StyledNode(id: "editor") continues to match stylesheet #editor rules.

Guinevere scoped data and animation migration

Existing GetValue, SetValue, GetFloat and SetFloat remain GUI-wide even within a data scope. Use EnterDataScope or SetDataScope with GetData/SetData to opt into scoped values. Supply the same named key when two call sites must share data; omitted keys identify each call automatically. GetData references remain stable across store growth and become detached after ClearData; reacquire them after clearing.

Within a frame, AnimateBool01 includes node, item and data context plus call-site occurrence. Use gui.AnimateBool01("visibility", target, duration, easing) for intentional sharing, and call it from the same locations in both passes. The first access selects the frame's target and sampled value; render-only target changes must be requested in a later frame. Standalone animations and unnamed GUI animation calls outside frames retain their contracts. The original method signature is unchanged; the animation identity and sampling behavior belongs to the next Guinevere major release.

Guinevere direct and fluent drawing migration

Drawing overloads with an explicit color return void and record compact primitive commands. Geometry-only DrawRect, DrawCircle, DrawTriangle and DrawBackgroundRect overloads return mutable Skia vector shapes for chained effects; DrawShape(position, shape) returns a translated mutable copy. For example, gui.DrawRect(rect, color) draws directly, while gui.DrawRect(rect, radius: 6).SolidColor(color) returns a fluent shape. Use gui.DrawBackgroundRect().SolidColor(color) for fluent backgrounds and gui.DrawBackgroundRect(color) for direct backgrounds. No-color backgrounds are fluent white shapes; pass null explicitly for a direct white background. Direct nullable rectangle overloads also require their color argument. Replace chained borders with gui.DrawRect(rect, radius).Stroke(color, thickness) or gui.DrawCircle(center, radius).Stroke(color, thickness). Turian engine-color drawing bridges remain direct void calls; pass color.ToGui() to fluent SolidColor or Stroke methods.

Background commands prepend one draw behind the node's other content. Translucent backgrounds therefore no longer accumulate opacity from duplicate draws. DrawTriangle and DrawTriangleFilled interpolate the supplied vertex colors, including the third vertex; omitted colors use the first color. Keep state and input calls at the same call site in both passes.

Guinevere code editor preview migration

Replace project or package references to Guinevere.TextEditor with Guinevere.Excalibur. The Guinevere namespace and gui.CodeEditor(CodeEditorState) API are preserved. The editor demo is now a Code Editor dock panel in Example-50. Excalibur requires com.BrunoMassa.SumTree 1.1.0; publish that version before restoring consumers on a clean machine.

Registry cache validation migration

HTTP and HTTPS registry resolution checks current trusted registry metadata before reusing a cached locked package. Removed or quarantined releases and unreachable registries fail resolution; ordinary yanked releases remain restorable from a lock. A cached HTTP installation is no longer sufficient for disconnected registry resolution. For offline work, configure an explicitly maintained local folder mirror and pin its public trust independently. Clients already distributed with the previous resolver retain their previous cache behavior until upgraded. These checks do not revoke code that is already running or has been copied outside the package manager.

Guinevere shared text layout migration

Replace gui.WrappedLabel(text, size, measureFont, drawFont: font) with gui.WrappedLabel(text, size, font: font). Remove the separate Skia measureFont argument and rename named drawFont arguments to font; measurement, drawing, wrapping, selection and hit testing now use the same Guinevere Font and cached TextLayout. Keep a Guinevere Font for custom typefaces, or omit font to inherit the scope font. Recompile callers and update delegates that bind the previous signature.

gui.LayoutText and gui.DrawRichText share rich-text geometry. Use TextLayoutOptions.FillWidth to wrap a text node to its final available width in the current frame. Recheck text sizing in constrained layouts because glyph advances now determine measurement; full editor bidi remains separate work. These changes are pending integration and package publication.

Guinevere typography and shaping migration

Recompile delegates bound to gui.LayoutText or gui.DrawRichText: their alignment parameter is now TextAlignment?. Passing null inherits the alignment from TextLayoutOptions; ordinary calls that pass a TextAlignment value continue to compile.

Spacing, tabs, indentation, justification, case conversion and kerning are configured through TextLayoutOptions, span styles, fluent methods or .pss. Core uses BasicTextShaper by default. For complex shaping, reference the optional MASS4.Guinevere.TextShaping package and assign gui.TextShaper = ComplexTextShaper.Instance. That package adds HarfBuzz and its native assets; changing the shaper invalidates cached layouts. Package publication and complete editor bidi remain pending.


← All docs Edit this page