{"id":13648834,"url":"https://github.com/rust-lang/rust-semverver","last_synced_at":"2025-10-04T05:31:07.965Z","repository":{"id":36980970,"uuid":"92445290","full_name":"rust-lang/rust-semverver","owner":"rust-lang","description":"Automatic checking for semantic versioning in library crates","archived":true,"fork":false,"pushed_at":"2023-07-17T03:21:55.000Z","size":1766,"stargazers_count":637,"open_issues_count":37,"forks_count":41,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-01-01T19:38:09.845Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rust-lang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-05-25T21:18:06.000Z","updated_at":"2024-11-28T16:33:22.000Z","dependencies_parsed_at":"2024-01-14T10:59:41.213Z","dependency_job_id":"b6d23d58-72ce-4b8a-9902-2bdfa198ab84","html_url":"https://github.com/rust-lang/rust-semverver","commit_stats":{"total_commits":842,"total_committers":35,"mean_commits":"24.057142857142857","dds":0.4655581947743468,"last_synced_commit":"821e059e8263e8bc76daea1a4be697954f7c2299"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-lang%2Frust-semverver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-lang%2Frust-semverver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-lang%2Frust-semverver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-lang%2Frust-semverver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rust-lang","download_url":"https://codeload.github.com/rust-lang/rust-semverver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235222539,"owners_count":18955327,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T01:04:35.604Z","updated_at":"2025-10-04T05:31:02.625Z","avatar_url":"https://github.com/rust-lang.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# rust-semverver\n\n## Deprecation notice\n\nThis crate has been deprecated, check the crates below for alternatives:\n- https://github.com/obi1kenobi/cargo-semver-checks\n- https://github.com/Enselic/cargo-public-api\n\n---\n\n[![Build Status](https://github.com/rust-lang/rust-semverver/workflows/CI/badge.svg?branch=master)](https://github.com/rust-lang/rust-semverver/actions?query=workflow%3ACI+branch%3Amaster)\n[![Current Version](https://img.shields.io/crates/v/semverver.svg)](https://crates.io/crates/semverver)\n\n`rust-semverver` is a tool to check semver-compliance in Rust library crates. The core of\nthe tool has been developed as a student project during the Google Summer of Code 2017.\n\nDetails on the work done during GSoC 2017 can be found\n[here](https://github.com/rust-lang/rust-semverver/blob/master/doc/gsoc.md).\n\n## Background\n\nThe approach taken is to compile both versions of the crate to `rlib`s and to link them as\ndependencies of a third, empty, dummy crate. Then, a custom compiler driver is run on the\nsaid dummy and all necessary analysis is performed in that context, where type information\nand other resources are available.\n\nMore information on the inner workings of the tool can be found\n[here](https://github.com/rust-lang/rust-semverver/blob/master/doc/impl_notes.md).\n\n## Installation\n\nThe tool is implemented as a cargo plugin. As of now, it can be obtained from this git\nrepository and compiled from source or installed from\n[crates.io](https://crates.io/crates/semverver). Keep in mind that only the pinned version(in [rust-toolchain])\nof the nightly toolchain is supported at any given time.\n\n\u003c!-- NOTE: Keep in sync with nightly date on rust-toolchain. --\u003e\nIt's recommended to use `nightly-2022-08-03` toolchain.\nYou can install it by using `rustup install nightly-2022-08-03` if you already have rustup.\nThen you can do:\n\n```sh\n$ rustup component add rustc-dev llvm-tools-preview --toolchain nightly-2022-08-03\n$ cargo +nightly-2022-08-03 install --git https://github.com/rust-lang/rust-semverver\n```\n\nYou'd also need `cmake` for some dependencies, and a few common libraries (if you hit\nbuild failures because of missing system-wide dependencies, please open an issue, so they\ncan be added here).\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\n  Manual installation and more details\n\u003c/summary\u003e\n\n```sh\n$ git clone https://github.com/rust-lang/rust-semverver\n$ cd rust-semverver\n$ cargo install\n```\n\nAt this point, the current development version can be invoked using `cargo semver` in any\ndirectory your project resides in. If you prefer not to install to `~/.cargo/bin`, you can\ninvoke it like so after building with a regular `cargo build`:\n\n```sh\n$ PATH=/path/to/repo/target/debug:$PATH cargo semver \u003cargs\u003e\n```\n\nIf you have built using `cargo build --release` instead, change the path to point to the\n`release` subdirectory of the `target` directory.\n\n\u003c/details\u003e\n\n## Usage\n\nBy default, running `cargo semver` in directory with a Cargo project will try to compare\nthe local version to the one last published on crates.io, and display warnings or errors for\nall changes found.\n\nInvoking `cargo semver -h` gives you the latest help message, which outlines how to use\nthe cargo plugin:\n\n```sh\n$ cargo semver -h\nusage: cargo semver [options]\n\nOptions:\n    -h, --help          print this message and exit\n    -V, --version       print version information and exit\n    -e, --explain       print detailed error explanations\n    -q, --quiet         suppress regular cargo output, print only important\n                        messages\n        --show-public   print the public types in the current crate given by\n                        -c or -C and exit\n    -d, --debug         print command to debug and exit\n    -a, --api-guidelines\n                        report only changes that are breaking according to the\n                        API-guidelines\n        --features FEATURES\n                        Space-separated list of features to activate\n        --all-features  Activate all available features\n        --no-default-features\n                        Do not activate the `default` feature\n        --compact       Only output the suggested version on stdout for\n                        further processing\n    -j, --json          Output a JSON-formatted description of all collected\n                        data on stdout.\n    -s, --stable-path PATH\n                        use local path as stable/old crate\n    -c, --current-path PATH\n                        use local path as current/new crate\n    -S, --stable-pkg NAME:VERSION\n                        use a `name:version` string as stable/old crate\n    -C, --current-pkg NAME:VERSION\n                        use a `name:version` string as current/new crate\n        --target \u003cTRIPLE\u003e\n                        Build for the target triple\n```\n\nThis means that you can compare any two crates' specified versions, as long as they are\navailable on crates.io or present on your filesystem.\n\n### CI setup\n\nAssuming you use a CI provider that gives you access to cargo, you can use the following\nsnippet to check your build for semver compliance, and enforce that version bumps are\ncarried out correctly with regards to the current version of your crate on crates.io:\n\n```sh\n# install a current version of rust-semverver\ncargo +nightly-2022-08-03 install --git https://github.com/rust-lang/rust-semverver\n# fetch the version in the manifest of your crate (adapt this to your usecase if needed)\neval \"current_version=$(grep -e '^version = .*$' Cargo.toml | cut -d ' ' -f 3)\"\n# run the semver checks and output them for convenience\ncargo semver | tee semver_out\n# fail the build if necessary\n(head -n 1 semver_out | grep \"\\-\u003e $current_version\") || (echo \"versioning mismatch\" \u0026\u0026 return 1)\n```\n\nMake sure you do the above with access to a nightly toolchain. Check your CI provider's\ndocumentation on how to do that.\n\n### JSON output\n\nBy passing the `-j` flag, all output on standard out is formatted as a machine-readable\nJSON blob. This can be useful for integration with other tools, and always generates all\npossible output (ignoring other output-related flags). The output format is defined as\nfollows:\n\nThe top level object contains the keys `old_version`, `new_version` and `changes`. The\nformer two hold a version number in the format `major.minor.patch`, the latter an object\ndescribing changes between the crate versions, which contains two arrays in the keys\n`path_changes` and `changes`.\n\nThe `path_changes` array contains objects describing item additions and removals, which\nhave the following keys:\n\n* `name`: The name of the item.\n* `def_span`: An object describing the location of the item in one of the crates.\n* `additions`: An array of spans that describe locations where the item has been added.\n* `removals`: An array of spans that describe locations where the item has been removed.\n\nAn example object might look like this:\n\n```json\n{\n  \"name\": \"NFT_META_CGROUP\",\n  \"def_span\": {\n    \"file\": \"/path/to/libc-0.2.48/src/unix/notbsd/linux/other/mod.rs\",\n    \"line_lo\": 776,\n    \"line_hi\": 776,\n    \"col_lo\": 0,\n    \"col_hi\": 40\n  },\n  \"additions\": [\n    {\n      \"file\": \"/path/to/libc-0.2.48/src/lib.rs\",\n      \"line_lo\": 195,\n      \"line_hi\": 195,\n      \"col_lo\": 16,\n      \"col_hi\": 23\n    }\n  ],\n  \"removals\": []\n}\n```\n\n\nThe `changes` array contains objects describing all other changes, which have the\nfollowing keys:\n\n* `name`: The name of the item\n* `max_category`: the most severe change category for this item, as a string.\n  * Possible values are `Patch`, `NonBreaking`, `TechnicallyBreaking`, and `Breaking`.\n* `new_span`: an object describing the location of the item in the new crate (see example).\n* `changes`: an array of 2-element sequences containing an error message and an optional\n  sub-span (`null` if none is present)\n\nAn example object might look like this:\n\n```json\n{\n  \"name\": \"\u003cnew::util::enumerate::Enumerate\u003cT\u003e as new::prelude::Stream\u003e\",\n  \"max_category\": \"TechnicallyBreaking\",\n  \"new_span\": {\n    \"file\": \"/path/to/tokio-0.1.17/src/util/enumerate.rs\",\n    \"line_lo\": 46,\n    \"line_hi\": 63,\n    \"col_lo\": 0,\n    \"col_hi\": 1\n  },\n  \"changes\": [\n    [\n      \"trait impl generalized or newly added\",\n      null\n    ]\n  ]\n}\n```\n\nFor reference, all objects describing spans have the same keys:\n\n* `file`: A file name.\n* `line_lo`: The line the span starts on.\n* `line_hi`: The line the span ends on.\n* `col_lo`: The column the span starts on.\n* `col_hi`: The column the span ends on.\n\n## Functionality\n\nThe guideline used to implement semver compatibility is the [API evolution\nRFC](https://github.com/rust-lang/rfcs/blob/master/text/1105-api-evolution.md), which\napplies the principles of semantic versioning to the Rust language's semantics. According\nto the RFC, most changes are already recognized correctly, even though some type checks\nstill behave incorrectly in edge-cases. A longterm goal is to fix this in the compiler.\n\nAt the time of writing, the following types of changes are recognized and classified\ncorrectly:\n\n* items moving from `pub` to non-`pub` and vice-versa\n* items changing their kind, i.e. from a `struct` to an `enum`\n* additions and removals of region parameters to and from an item's declaration\n* additions and removals of (possibly defaulted) type parameters to and from an item's\n  declaration\n* changes to the variance of type and region parameters\n* additions and removals of enum variants\n* additions and removals of enum variant- or struct fields\n* changes from tuple structs or variants to struct variants and vice-versa\n* changes to a function or method's constness\n* additions and removals of a self-parameter on methods\n* additions and removals of (possibly defaulted) trait items\n* correct handling of \"sealed\" traits\n* changes to the unsafety of a trait\n* type changes of all toplevel items, as well as associated items in inherent impls and\n  trait definitions\n* additions and removals of inherent impls or methods contained therein\n* additions and removals of trait impls\n\nKeep in mind however that the results presented to the user are merely an approximation of\nthe required versioning policy.\n\n## Contributing\n\nPlease see\n[CONTRIBUTING.md](https://github.com/rust-lang/rust-semverver/blob/master/CONTRIBUTING.md).\n\n## License\n\n`rust-semverver` is distributed under the terms of the 3-clause BSD license.\n\nSee LICENSE for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frust-lang%2Frust-semverver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frust-lang%2Frust-semverver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frust-lang%2Frust-semverver/lists"}