<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="../assets/eeco_logo_dark.png">
    <img src="../assets/eeco_logo_light.png" alt="eeco" width="280">
  </picture>

<h1>Upgrading</h1>

<p><i>How to move between eeco releases.</i></p>

<p>
    <a href="../README.md"><b>README</b></a> ·
    <a href="../VISION.md"><b>Vision</b></a> ·
    <a href="COCKPIT.md"><b>Cockpit</b></a> ·
    <a href="USAGE.md"><b>Usage</b></a> ·
    <a href="ARCHITECTURE.md"><b>Architecture</b></a> ·
    <a href="PUBLIC_API.md"><b>Public API</b></a> ·
    <a href="../EXTENDING.md"><b>Extending</b></a> ·
    <a href="../CONTRIBUTING.md"><b>Contributing</b></a> ·
    <b>Upgrading</b> ·
    <a href="../VERSIONING.md"><b>Versioning</b></a> ·
    <a href="../CHANGELOG.md"><b>Changelog</b></a> ·
    <a href="../SECURITY.md"><b>Security</b></a>
  </p>

</div>

---

How to move between eeco releases. From v0.1.0 onward this file is the
canonical upgrade log: each release that needs upgrade steps or carries a
breaking change lands a section here.

## v0.1.0 and onward

eeco is **pre-stability** on the `v0.x` line. The public surface
(commands, flags, exit codes, workflow contract, config keys, memory
frontmatter, queue and ledger formats, builtin workflow names — see
[`PUBLIC_API.md`](PUBLIC_API.md)) follows semver under the pre-1.0 caveat
of [`VERSIONING.md`](../VERSIONING.md) §2.1: while eeco is pre-1.0 a MINOR
MAY make a breaking change, called out here and in the
[`CHANGELOG.md`](../CHANGELOG.md) `### Changed` entry with its migration
path; a PATCH never breaks. Once v1.0.0 ships, a breaking change requires
a major-version bump and a dedicated section in this file.

Each release section that needs one will document:

- **Required steps** — anything an existing workspace must do to remain
  valid (usually nothing for a PATCH; pre-1.0 a MINOR may carry steps).
- **Removed or renamed surfaces** — every breaking change with the old
  name, the new name, and a migration note.
- **New optional features** — config keys, commands, or workflows added
  in the release that an existing workspace can adopt at its own pace.

A workspace from any `v0.x` release reads cleanly with any later `v0.x`
release: an unknown `config.local` key is tolerated; an unknown queue or
memory field is preserved on write.

## Migrating a legacy workspace

A repository that already ran an older eeco workspace at `<repo>/.eeco`
moves to the per-user layout with one command:

```
eeco migrate v1
```

This relocates the workspace to `<repo>/<username>/.eeco`, relinks the
hook ledger, and rewrites the `.gitignore` line — idempotently. Running
`eeco init` inside such a repository offers the same migration
interactively.

> **Note** — the `v1` in `eeco migrate v1` names the **workspace-layout
> generation** (the per-user `<username>/.eeco` layout), **not** the
> product version. The verb keeps its name as frozen CLI surface even
> though the product re-launches at v0.1.0.

---

[← Prev: Contributing](../CONTRIBUTING.md) · [Next: Versioning →](../VERSIONING.md)