Breaking change detection

[amckinney]

Overview

We're beginning to design a CLI command that users can run to:

1. Detect API breaking changes.
2. Determine the next semantic version based on the full set of API changes.
3. Generate a CHANGELOG.md entry outlining a human-readable representation of the API changes.

Discoverability

All of these commands boil down to managing and working with API changes. We want these commands to be discoverable (i.e. what do I see when I run fern --help), but we also want to consolidate these operations under a common umbrella.

We have plans for a CLI hierarchy overhaul in the CLI's first major version (i.e. 1.0.0), so we aim to design these new commands in a way that mirrors the new model.

Commands

We propose the following set of commands all under the new sdk subcommand:

1. fern sdk changelog --from <from> [--from-version <version>] [--output={filepath,json,text,version}]
2. fern sdk version --from <from> [--from-version <version>]
   • This is shorthand for --output version flag using the command above.

Note that the same --api filter will be available for users that have multi-api repository setups. The --from-version flag is marked as optional to start because the CLI can (eventually) determine the current version for a given SDK on its own.

Examples

# Generate a CHANGELOG.md entry in 'keep a changelog' format (default).
$ fern sdk changelog --api default --from bac7962 --from-version 1.0.0
## [2.0.0]

### Added

- Added the `limit` query parameter to the `GET /users` endpoint.

### Removed

- The `GET /organizations` endpoint was removed.

# Generate the next semantic version.
$ fern sdk changelog --api default --from bac7962 --from-version 1.0.0 --output version
2.0.0

# Generate the next semantic version.
$ fern sdk version --api default --from bac7962 --from-version 1.0.0
2.0.0

# Generate the filepath format, which is suitable for IDE integrations (e.g. ALE).
$ fern sdk changelog --api default --from bac7962 --output filepath
fern/apis/default/openapi/openapi.yml:37:12:The 'GET /organizations' endpoint was removed

[amckinney]

To start, we redesigned this as the fern diff command introduced here, which acts upon two intermediate representations. In the future, we can add the flashy functionality outlined above, but it's best to start with more modular components (like the Unix Philosophy suggests). With this, breaking change detection can be more easily used in a variety of contexts, such as in custom shell scripts.

[nbsp]

@amckinney design question around CHANGELOG.md: do you plan to follow a standard changelog spec, or have your own format? changelogs are generally all over the place, and the only successful attempt to standardize them has been https://keepachangelog.com, though it has some extra required metadata in the form of "is this an addition/change/deletion/security/etc", which might not neatly fit here.