Foreword

This book's goal is to hold and maintain informations on how the innards of cargo-breaking works together to compare two versions of a library and display the differences between both.

Example:

$ cargo breaking
- user::User::from_str
≠ user::User
+ user::User::from_path
+ user::User: Debug

Next version is: 3.0.0

Installation

cargo-breaking needs the nightly toolchain to be installed to work correctly, but can be compiled with any toolchain. It can be compiled from sources with the following commands:

$ git clone https://github.com/iomentum/cargo-breaking
$ cd cargo-breaking
$ cargo install --path ./

You may need to add the --force argument to the last command if you're upgrading from a previous version.

Git workflow

Most work is commited in separate branch, before getting merged to main all at once, once we're satisfied with the refactoring, fixes, and features added. These branches are named scrabsha/iter-dd-mm-yy, representing the date at which the iteration is started (for instance, scrabsha/iter-19-06-21).

Installing cargo-breaking from the following branches give you the latest changes. It may have instabilities, though.

Process

This section describes the flow of the cargo-breaking application.

Overview

The process used by cargo-breaking can be summarized like this:

  • 2.2: The configuration is parsed from the cli args

  • 2.3: The git repository informations are created from the env

  • 2.4: The crate version is fetched from the manifest

  • 2.5: The "current library" and the "target library to run against" are collected as AST with rustc

  • 2.6: Both libraries are compared against each other to collect removals, additions and modifications

  • 2.7: The results are gathered in a diagnosis structure

  • 2.8: The "best" next version is suggested from the diagnosis

Configuration

WORK IN PROGRESS

Repository

WORK IN PROGRESS

Manifest

WORK IN PROGRESS

API Extraction

WORK IN PROGRESS

Comparator

WORK IN PROGRESS

Diagnosis

WORK IN PROGRESS

Next Version

WORK IN PROGRESS

Book

Mdbook is needed to get running this book:

$ cargo install mdbook
$ cd book
$ mdbook serve --dest-dir ../docs

Building the book

This updates the book so it is updated on push.

// TODO! add this as a pre-commit hook

$ cd book
$ mdbook build --dest-dir ../docs