agentleFS
vchelaruvchelaru/Gum/.claude/skills/gum-project-versioning/SKILL.md

gum-project-versioning

Skill655 starsChanged 2 months agoMITView on GitHub

Gum's .gumx schema versioning and migration strategy. Triggers: shape changes to GumProjectSave, ElementSave, or any serialized save class — version bumps, backward-compat shims, XmlSerializer-aware properties that must round-trip across tool versions.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Bundle multiple schema changes into one bump: when possible.

    line 60
  2. Distinctive:

    If you add a new property and keep the old one as a shim, know these:

    line 66
  3. Distinctive:

    Always emit the legacy element: when the new one is populated.

    line 74

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Gum Project Versioning Reference

The GumxVersions enum

Located in GumDataTypes/GumProjectSave.cs. The enum gains one entry per breaking schema change; the earliest entries cover the verbose→compact XML shift, later ones reserve slots for new variable surfaces. Read the enum itself for the current list and each entry's doc comment — don't rely on a copy here.

NativeVersion is the highest version this tool build supports / writes.

Ctor default vs. new-project factories — they intentionally differ

The GumProjectSave constructor does NOT default to NativeVersion. It defaults to an older version on purpose: the ctor default is the fallback for deserialized files that lack a Version element, so a legacy file reads back as the older version and the variable-grid version gate keeps hiding newer-only variables on it.

A brand-new project is the opposite case — it seeds the latest standard-element variable surface up front, so it is honestly at NativeVersion. The new-project factories (ProjectManager.CreateNewProject for the tool, ProjectCreator.Create for headless/CLI) therefore stamp Version = NativeVersion explicitly in their initializers rather than relying on the ctor default. When adding a new way to create a project, set the version there too — and keep the verbatim-copied template .gumx files (Tools/Gum.ProjectServices/Templates/: CLI, Forms, every theme) in step: bumping NativeVersion requires bumping <Version> in every one of them and adding the new variable to each template's Standards/*.gutx, or FormsTemplateCreatorTests (Create_ShouldProduceLoadableProject, Create_ShouldNotDriftFromDefaultStandards) fail. verify.ps1 only runs test classes you edited, so run Tests/Gum.ProjectServices.Tests in full after any bump.

A version can gate behavior, not only variables

FontCachePathHash (6) gates how a font file's cache name is built (GumProjectSave.UsesPathHashedFontCacheNames), so projects below it keep the names their shipped .fnt files already use. A bump that renames shipped files must also rename the template assets that use them: the Forms theme templates' FontCache folders hold hashed names, and FormsThemesTemplateTests.FontCache_ShouldOnlyContainFontsTheTemplateUses fails when they drift. Keep the bumped template .gumx files' line endings and (missing) final newline, or TemplateResaveStabilityTests fails on a one-byte difference.

The standard-element back-fill gate — tag new standard variables (FRB #1881)

On every load, GumProjectSaveExtensionMethods.Initialize back-fills each standard element with the tool's current StandardElementsManager default variables. This is version-gated: it skips any default variable whose VariableSave.MinimumGumxVersion exceeds the project's Version. When you add a variable to a standard element's default state that an older runtime won't have, you MUST tag it — pass minimumGumxVersion: to the Add*Variables helper, or set MinimumGumxVersion = … on the inline new VariableSave { … }. Pin it to the version that introduced the surface (e.g. ShapeVariableExpansion), not the floating NativeVersion — a floating tag would gate the variable out of projects that legitimately have it after the next bump.

Skip the tag (leave it 0 = always back-fill) only for variables every supported runtime already has. Forgetting the tag is exactly how FRB #1881 happened: opening a pre-v3 project injected the v3 shape surface into its .gutx, and FRB1 (which generates its own runtime classes from the standard elements) then emitted code referencing properties its pinned older runtime lacked — a wall of CS0246. The variable-grid display gate (ShapeVariableVersionGate) reads the same tag for every standard element type, so a tagged variable is hidden on older projects with no further entry; its name map and the AlwaysVisibleTaggedNames exemptions (Stroke*, Blend) only cover pre-tag cases. The runtime GumSyntaxVersion codegen gate is separate and has its own list.

Deprecated standard types are a separate mechanism from version gating

A standard element can be excluded from new/back-filled projects without any GumxVersions bump: StandardElementsManager._deprecatedStandardTypeNames (e.g. ColoredRectangle, superseded by the v3 Rectangle) stays in mDefaults for legacy-load correctness but is filtered out of SeedableStandardTypes, which both new-project creation and the load-time back-fill read from. Seeing a deprecated standard in an old project doesn't mean its version requires it — check SeedableStandardTypes before assuming a standard is version-gated rather than deprecated.

The three load-time behaviors

ProjectManager.LoadProject (~line 201 and ~288 per recent research) compares the file's Version against NativeVersion (items 1 and 3) and AttributeVersion (item 2):

  1. File version > NativeVersion → dialog: "saved with a newer version of Gum... Please update Gum." File is rejected.
  2. File version < AttributeVersion → Output-tab warning with an upgrade docs link (https://docs.flatredball.com/gum/gum-tool/upgrading/upgrading-file-gumx-version). File still opens and works.
  3. File version == NativeVersion → normal load.

Save doesn't auto-bump

This is unusual. Most authoring tools silently upgrade on save. Gum does not — a file loaded as v1 stays v1 after the user re-saves it. Upgrading is a user-initiated action following the docs link. Don't "fix" this without discussion.

XmlSerializer tolerance as the migration mechanism

There is no explicit migration pass for v1 → v2. Instead:

  • GumFileSerializer (in GumDataTypesNet6/) builds separate serializers (GetCompactSerializer, GetLegacyInstancesCompactSerializer, GetGumProjectCompactSerializer) using XmlAttributeOverrides to handle the attribute-vs-element shape differences.
  • Unknown XML elements are silently ignored by XmlSerializer, so adding a new element to a serialized class is inherently forward-compatible: old tools just skip it.

This means most schema changes don't require a version bump.

Bump-vs-don't-bump decision framework

  • Adding a new optional field → don't bump. Old tools ignore it.
  • Adding a new field while replacing/renaming an old one → don't bump, if you keep the old field as a backward-compat shim (an always-serialized view over the new one so old tools still read something sensible).
  • Removing a field with no shim, or making a breaking semantic change → bump. Accept the forward-compat barrier (old tools refuse the file).
  • Bundle multiple schema changes into one bump when possible.

The LocalizationFile → LocalizationFiles change in issue #2512 used the no-bump route: new List<string> property plus the legacy string property kept as a shim reading/writing index 0.

Writing backward-compat shims — XmlSerializer gotchas

If you add a new property and keep the old one as a shim, know these:

  1. [Obsolete] alone silently drops the property from XML output. XmlSerializer skips [Obsolete] members. If you need a shim to keep serializing, use [EditorBrowsable(EditorBrowsableState.Never)] plus an explicit [XmlElement("OldName")] attribute instead of [Obsolete].
  2. List<T> appends; T[] replaces. On deserialize, XmlSerializer calls Add on a List<T> property once per child element — so if the old element appears before the new one, both contribute and you end up with duplicates. Arrays are assigned via the setter, which replaces. If your deserialized shape might contain both old and new elements, serialize as T[] (with an [XmlArray] attribute) and expose a [XmlIgnore] List<T> that syncs.
  3. Declaration order affects which setter wins when both old and new elements are present in XML. XmlSerializer applies properties in document order. If your shim and new property both set the same underlying state, putting the legacy property first (so the new property's setter fires last) is the intended round-trip shape.
  4. Always emit the legacy element when the new one is populated. That way, an older tool opening a new file still reads something — typically the first entry of a list.

Related skills

  • gum-tool-save-classes — broader overview of the save/load data model, ShouldSerialize*, [XmlIgnore], two-phase loading.
  • gum-localization — localization-specific file loading, the place where LocalizationFile(s) is consumed.
  • gum-tool-codegen — .codsj files have their own Version field (separate from .gumx versioning), migrated in CodeOutputProjectSettingsManager.MigrateIfNeeded on load. Don't auto-save — let the next user save persist the new version. Each version bump needs a comment explaining what it does and why.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.