# orca.upgrade

> A module of morca's API.

A release's upgrade steps (#323): what has to be done before or after a deploy, which a project's image ships in `upgrade.toml` and the Hetzner deploy shows or runs (`deploy/hetzner/deploy.sh`).

```toml
[[version]]
version = "1.2.0"

[[version.step]]
id = "1.2.0-retool"      # unique and stable
when = "after"           # before | after (the default)
run = "orca backfill --rerun mojo_retool @all"   # an orca command

[[version.step]]
id = "1.1.0-egress-hf"
when = "before"
manual = "The console downloads its model from huggingface.co: allow outbound HTTPS."
```

`orca upgrade --from <deployed> --to <new>` prints the steps of every
version after `--from` up to `--to`, a line each:

    step<TAB><id><TAB><before|after><TAB><run|manual><TAB><command or text>

What makes a step run once is that range: a deploy from 1.1.0 to 1.2.0 takes
1.2.0's steps, and the next deploy, from 1.2.0, doesn't. Nothing is recorded
in the database. A `--from` that isn't a version (a commit, empty) takes
only `--to`'s steps.

## Structs

### `UpgradeStep`

```mojo
struct UpgradeStep
```

Implements: `Copyable`, `Movable`

Fields:

- `version: String`
- `id: String`
- `when: String`: `before` or `after`.
- `kind: String`: `run` or `manual`.
- `text: String`: The command (`orca ...`) or the instructions.

## Functions

### `version_parts`

```mojo
def version_parts(v: String) -> List[Int]
```

`1.2.0` (or `v1.2.0`, `1.2.0-rc1`) as `[1, 2, 0, pre]`, `pre` 0 for a prerelease and 1 for a release, so a prerelease sorts before its release; empty when `v` isn't a version (a commit, say).

### `version_less`

```mojo
def version_less(a: List[Int], b: List[Int]) -> Bool
```

### `parse_upgrade`

```mojo
def parse_upgrade(text: String) -> List[UpgradeStep]
```

The steps of an `upgrade.toml`, in the file's order. Raises for a version that isn't one, a step without an id, with both or neither of `run` and `manual`, a `when` that isn't `before` or `after`, a `run` that isn't an `orca` command, or an id used twice.

### `select_steps`

```mojo
def select_steps(steps: List[UpgradeStep], from_v: String, to_v: String, when: String = "") -> List[UpgradeStep]
```

The steps of each version after `from_v` up to `to_v`, in version order and then the file's (only `to_v`'s when `from_v` isn't a version), and only those `when` (`before`, `after`) when given.

### `step_line`

```mojo
def step_line(s: UpgradeStep) -> String
```

### `upgrade_command`

```mojo
def upgrade_command(args: List[String]) -> Int
```

`orca upgrade [--file F] [--from V] --to V [--when before|after]`.

## Aliases

### `DEFAULT_FILE`

```mojo
comptime DEFAULT_FILE = "/opt/orca/upgrade.toml"
```