# v5 Breaking Changes

This page summarizes the main breaking changes in v5 and how to upgrade from previous versions.

## Upgrade Path

If you installed a previous JavaScript-distributed version globally, remove it first:

```bash
yarn global remove fotingo
npm uninstall -g fotingo
```

Then install v5 using one of the supported distribution methods:

```bash
# Homebrew
brew tap tagoro9/tap
brew install fotingo
xattr -dr com.apple.quarantine /opt/homebrew/bin/fotingo

# Or install from source
go install github.com/tagoro9/fotingo@latest
```

The extra `xattr` step is needed on macOS when Homebrew leaves the `com.apple.quarantine` attribute on the downloaded `fotingo` binary. Gatekeeper can treat the binary as quarantined and block execution until that attribute is removed.

You can also download binaries from GitHub Releases.

After installing v5, the recommended migration step is to re-authenticate in the new CLI:

```bash
fotingo login
```

Re-authenticate all services when prompted (GitHub and Jira) so credentials are stored in the v5 configuration/auth flows.

## Major Changes in v5

## 1. Runtime and Distribution Model

- `fotingo` is now a Go CLI (native binary distribution).
- Node.js runtime dependency for the CLI itself is removed.

Migration note:

- Reinstall using Homebrew, `go install`, or release binaries after removing old global npm/yarn installs.

## 2. Configuration Format and Locations

- Configuration is YAML-based.
- Config resolution now uses:
  - project override: `.fotingo.yaml`
  - user config: `~/.config/fotingo/config.yaml`
- Canonical Jira site key is `jira.root`.

Migration note:

- Move or recreate settings in the YAML config locations above if you were using legacy setup patterns.

## 3. Authentication Behavior

- GitHub auth now supports:
  - OAuth flow via Fotingo GitHub App (installable during auth flow), or
  - classic PAT (`repo` scope) token auth.
- Jira auth now emphasizes API token auth for most users.
- Jira OAuth is only for internal builds compiled with Jira OAuth credentials (client ID/client secret), not general distributed binaries.

Migration note:

- Re-run `fotingo login` after upgrading and follow the interactive prompts to refresh stored credentials in v5 format.

## 4. Command Surface and Workflow Semantics

Compared with the v4 README command surface (`start`, `review`, `release`, `open`, `verify`, `inspect`), v5 introduces and expands command workflows in a few key areas:

- `verify` command:
  - no longer exists as a top-level command in v5.
- `config` command set:
  - inspect and update effective configuration via CLI subcommands (`view`, `get`, `set`).
- `cache` command set:
  - inspect cached entries and clear cache state directly from CLI.
- `ai setup`:
  - install provider-targeted AI skills for tools like Cursor, Codex, and Claude Code.
- machine-readable output:
  - most user-facing commands now support `--json` output for automation/integration usage.
- `review`:
  - template-placeholder override workflow (`--template-summary`, `--template-description`) for structured PR generation.
- `inspect`:
  - already existed in v4, but now has improved output behavior (commit list scoped from merge-base and richer Jira relationship context such as parent/epic when available).

Migration note:

- Review existing scripts and wrappers to adopt `config`/`cache` commands where you previously edited files or cleared cache data manually.

## 5. Performance and Caching Changes

- Participant directory caching for review resolution was expanded (including collaborators/org members).
- Start/review internal performance instrumentation and lazy workflow paths were improved.

Migration note:

- First run after upgrade may still perform initial fetches; subsequent runs should benefit from cache reuse.

## 6. Release/Build Environment Variable Names (Maintainers)

Release workflow OAuth injection variables now use `FOTINGO_` prefixes.

- `FOTINGO_GH_OAUTH_CLIENT_ID`
- `FOTINGO_JIRA_OAUTH_CLIENT_ID`
- `FOTINGO_JIRA_OAUTH_CLIENT_SECRET`

Migration note:

- Update repository secrets and local release env exports before running prerelease/release pipelines.

## Post-Upgrade Checklist

- Run `fotingo login` and re-authenticate all services.
- Confirm `fotingo --help` shows expected commands.
- Run `fotingo inspect` in a working branch to verify Jira/GitHub connectivity.
- Run your normal `fotingo start ...` and `fotingo review ...` flow once to validate templates and auth.