Module: Mxup::Migrations

Defined in:

lib/mxup/migrations.rb

Overview

The config format's history, one entry per major version, plus the renderer behind mxup migrations.

A new config format generation ships with a new mxup major, and mxup goes on reading every older generation (see Config#resolve_format_major!) — so every major above the first has exactly one entry here describing what changed and how to move a config written for the previous one. When cutting a new major, add an entry and bump Config::CURRENT_FORMAT_MAJOR to match its to.

Constant Summary

ENTRIES =

from/to are majors. changes each have a title and, for readability at the terminal, pre-wrapped before / now / fix prose.

[
  {
    from: 0,
    to: 1,
    changes: [
      {
        title: 'Profiles select windows additively instead of subtracting them',
        before: 'Every window in `windows:` ran. A profile overrode some of ' \
                'them and dropped others with `~`, so `staging: {}` meant ' \
                '"run everything, unchanged".',
        now:    '`windows:` is a catalog and nothing in it runs on its own. ' \
                'Each profile lists the windows it runs, and several profiles ' \
                'can be selected at once (`-p a,b`) — the live set is their ' \
                'union. A window no selected profile lists stays down.',
        fix:    'In every profile, list the windows it should run: `name: {}` ' \
                'to include one as declared in the catalog, or a non-empty ' \
                'block to include it with overrides. A profile that listed ' \
                'nothing (`staging: {}`) must now name every window it wants, ' \
                'and a profile that dropped windows with `name: ~` should ' \
                'instead list the ones it keeps. `~` still parses, but it now ' \
                'means "veto": it collides if another selected profile ' \
                'includes that window.'
      },
      {
        title: '`default_profile` may name several profiles',
        before: 'A single profile name.',
        now:    'A name or a list of names, selected together when ' \
                '`--profile` is omitted.',
        fix:    'Nothing to change — a single name still works.'
      },
      {
        title: '`mxup_version` selects which format a config is read as',
        before: 'The key did not exist.',
        now:    'A config with no `mxup_version` is read as the 0.x format — ' \
                'profiles included — so it goes on running under mxup 1.x ' \
                'exactly as it did under 0.3.1. The key is what opts a ' \
                'config in to the format described above.',
        fix:    'Nothing, to keep a 0.x config working. Set ' \
                "`mxup_version: '1'` once you have migrated its profiles; " \
                'that is also what unlocks selecting several at once.'
      }
    ]
  }
].freeze

Class Method Summary

• .render(out: $stdout) ⇒ Object

Class Method Details

.render(out: $stdout) ⇒ Object

# File 'lib/mxup/migrations.rb', line 61

def render(out: $stdout)
  out.puts "mxup #{VERSION} — config format changes by major version."
  out.puts

  ENTRIES.each { |entry| render_entry(entry, out) }

  out.puts '`mxup_version` names the generation a config is written for, and'
  out.puts 'mxup reads every generation up to its own — so a config with no'
  out.puts '`mxup_version` keeps running as 0.x. Set it to the major you have'
  out.puts 'migrated to.'
end