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