# Migrating to ChordSketch v0.3.0

v0.3.0 renames the core AST/parser crate from `chordsketch-core` to
`chordsketch-chordpro`. The change is purely a naming one — public
APIs are unchanged and there are no behavioural differences. It is
a prerequisite for the v0.3.0 multi-format track
([#2050](https://github.com/koedame/chordsketch/issues/2050)): the
upcoming `chordsketch-ireal`, `chordsketch-convert`, and
`chordsketch-render-ireal` crates would otherwise have to coexist
with a crate whose name implies it is the only format.

This guide is deliberately boring and mechanical. If you have to
think about any step below, please
[file an issue](https://github.com/koedame/chordsketch/issues/new)
— the migration path should not require judgement.

## TL;DR

| Surface | Do you need to change anything? |
|---|---|
| Rust (direct `chordsketch-core` consumer) | **Yes** — rename the dependency and update `use` paths. |
| `@chordsketch/wasm` (npm) | No |
| `@chordsketch/node` (napi) | No |
| `chordsketch` (PyPI / UniFFI) | No |
| `ChordSketch` (Swift Package / XCFramework) | No |
| `me.koeda:chordsketch` (Maven Central) | No |
| `chordsketch` (RubyGems) | No |
| `chordsketch` (CLI / binary) | No |
| VS Code / Zed / JetBrains extensions | No |
| Helix (manual grammar + LSP config) | No |

If you do not depend on `chordsketch-core` from Rust, you do not need
to do anything.

## Rust consumers

If your `Cargo.toml` references `chordsketch-core`, update it to
`chordsketch-chordpro`:

```diff
 [dependencies]
-chordsketch-core = "0.2"
+chordsketch-chordpro = "0.3"
```

Then update every `use` path in your Rust source:

```diff
-use chordsketch_core::Parser;
-use chordsketch_core::ast::Song;
+use chordsketch_chordpro::Parser;
+use chordsketch_chordpro::ast::Song;
```

For a bulk-rename on an existing Cargo workspace, the following two
commands do the full migration in place. They use `perl -pi` rather
than `sed -i` because `perl` ships with both macOS (BSD) and Linux
and supports the same `\b` word-boundary syntax on both — GNU `sed`
and BSD `sed` disagree on both `\b` and the `-i ''` backup-suffix
convention, so a single `sed` one-liner cannot cover both.

```bash
# Cargo.toml dependency spec
find . -name Cargo.toml -print0 \
  | xargs -0 perl -pi -e 's/\bchordsketch-core\b/chordsketch-chordpro/g'

# Rust source (both `chordsketch_core::` paths and any `extern crate` line)
find . -name '*.rs' -print0 \
  | xargs -0 perl -pi -e 's/\bchordsketch_core\b/chordsketch_chordpro/g'
```

The word-boundary anchors (`\b...\b`) reduce the chance of rewriting
unrelated identifiers that happen to contain the substring; they do
not eliminate it. Hyphens are non-word characters, so the right-hand
anchor (between `core` and a trailing `-`) still matches, meaning a
hypothetical `chordsketch-core-extra` would also be rewritten. The
left anchor *does* correctly prevent matches like
`mychordsketch-core`. No such sibling crate exists today, but review
the diff with `git diff` before committing in any case.

After editing:

```bash
cargo build --workspace   # must succeed; Cargo refreshes the lockfile on first build
cargo test  --workspace   # public API is identical — every prior test still passes
```

If `cargo build` reports `chordsketch-chordpro` cannot be found on
crates.io, confirm the v0.3.0 release has been published; until then,
add a Git dependency temporarily:

```toml
chordsketch-chordpro = { git = "https://github.com/koedame/chordsketch", tag = "v0.3.0" }
```

## All other bindings

Every non-Rust binding wraps the core crate behind a stable
language-idiomatic surface (UniFFI for Python / Swift / Kotlin / Ruby,
napi-rs for Node.js, wasm-bindgen for the browser). **None of those
surfaces reference `chordsketch-core` directly**, so consumers of:

- `npm install @chordsketch/wasm` / `npm install @chordsketch/node`
- `pip install chordsketch`
- `ChordSketch` Swift Package / XCFramework
- `me.koeda:chordsketch` Maven dependency
- `gem install chordsketch`

will see no API differences. The published package names and version
numbers move forward normally; bump the pinned version as you would
for any minor release.

## CLI / binary

The `chordsketch` binary (Cargo, Homebrew, Scoop, winget,
Chocolatey, `.deb`, `.rpm`, Arch, Docker, GHCR) is packaged as a
single executable. The crate rename happens inside the workspace and
is invisible to binary users — no command-line flags, input formats,
or output formats change. Existing scripts that invoke
`chordsketch parse`, `chordsketch render`, etc. continue to work
without modification.

## Editor extensions

The VS Code, Zed, and JetBrains extensions bundle the
`chordsketch-lsp` binary (or route through `chordsketch` directly).
The LSP protocol surface is unchanged; extension users receive
v0.3.0 as a transparent update through their editor's marketplace.

Helix is supported via manually configured grammar + LSP settings
(see [`docs/editors.md`](../editors.md) for the `languages.toml`
snippet) — there is no packaged extension. Helix users who have
installed `chordsketch-lsp` from a release artifact or
`cargo install` simply upgrade the binary; the LSP protocol surface
is unchanged.

## Rolling back

If you need to pin to the pre-rename API on a specific hotfix branch,
the last release that published `chordsketch-core` is v0.2.2. Pin
that exact version:

```toml
chordsketch-core = "=0.2.2"
```

The 0.2.x line will not receive new features, but is suitable for
short-term blockers where the migration cannot yet be scheduled.

## Related issues and PRs

- Core rename: [#2056](https://github.com/koedame/chordsketch/issues/2056)
  / [#2097](https://github.com/koedame/chordsketch/pull/2097)
- v0.3.0 tracker: [#2050](https://github.com/koedame/chordsketch/issues/2050)
- SDK & UI libraries tracker: [#2039](https://github.com/koedame/chordsketch/issues/2039)