The purpose of this tool is to help people to publish crates following the semver specification.
Right now if you're building a new crate publishing new versions includes a high amount of work. You need to decide if the new version will be either a new Major, Minor or Patch version. If that decision is made, the next step is to write a changelog with all the things changed. Then increase the version in
Cargo.toml. Make a commit and a new tag for the new version and lastly publish it to crates.io.
If you need to repeat these steps every time, chances are high you make mistakes.
semantic-rs automates all these steps for you so you can focus more on developing new features instead.
- Install semantic-rs on your machine.
- Follow the Angular.js commit message conventions when you commit changes to your repository
- When you're done with development, run semantic-rs
- Based on your changes it determines the next version number, generates a changelog, commits it and creates a new tag
- It also increases the version number in
cargo packagefor you
- Creates a release on GitHub
- Publishes the new version to crates.io
You need the following data beforehand:
semantic-rs depends on some data being passed in via environment variables. In our examples we specify those variables explicitly but if you run semantic-rs frequently you may want to configure those in your shell's configuration file.
GIT_COMMITTER_EMAIL is optional. If you omit those, we default to the settings from your (global) git configuration.
If you run semantic-rs without any arguments, it operates on your current working directory:
$ export GH_TOKEN=<GHTOKEN> $ export CARGO_TOKEN=<CARGOTOKEN> $ export GIT_COMMITTER_NAME=<Your name> $ export GIT_COMMITTER_EMAIL=<Your email> $ semantic-rs #...
By default it runs in dry-run mode. This means it doesn't perform changes automatically. You see which steps would be performed and also the resulting changelog.
To perform the changes, pass
-w as an argument:
$ semantic-rs -w yes
This performs the following operations:
- Create or update
Changelog.mdcontaining everything that changed
- Create a new commit containing the following changes:
- An updated
Cargo.tomlwith the new version number
- Create a new annotated git tag pointing to the last commit created recently and including the Changelog for the new version
- A new version published to crates.io
- A new release on GitHub
- Push the new commit and tag to GitHub
Running the tests
To run semantic-rs's tests:
- unit tests:
- integration tests:
- OpenSSL development package
- Mac Homebrew:
- Rust 1.5 or later
For OS X > 10.10
Note that since OS X 10.11 Apple doesn't ship development headers for OpenSSL anymore. In order to get it working, you need to run cargo with these variables configured:
OPENSSL_INCLUDE_DIR=`brew --prefix openssl`/include \ OPENSSL_LIB_DIR=`brew --prefix openssl`/lib \ cargo build
Clone this project:
$ git clone firstname.lastname@example.org:semantic-rs/semantic-rs.git
As a test project you can use this one: https://github.com/badboy/test-project.
Clone it as well:
$ git clone https://github.com/badboy/test-project.git
In your top level directory there should be now the following two folders:
$ ls -l semantic-rs test-project
Change into the semantic-rs folder and run
Then you can run semantic-rs against the test project:
$ cargo run -- -p ../test-project Compiling semantic-rs v0.1.0 (file:///Users/janschulte/projects/semantic-rs/semantic-rs) Running `target/debug/semantic-rs -p ../test-project` semantic.rs 🚀 Analyzing your repository Current version: 2.0.3 Analyzing commits Commits analyzed. Bump would be Minor New version would be: 2.1.0 Would write the following Changelog: ==================================== ## v2.1.0 (2016-07-03) #### Features * Math mode ([24afa46f](24afa46f)) #### Bug Fixes * Into the void ([9e54f4bf](9e54f4bf)) ==================================== Would create annotated git tag
-w yes was not passed, it only prints out what it would do. Note that if you run it on your local machine the output may differ.
Run semantic-rs in CI environment
Make sure to set the
CI=true environment variable to disable dry-run mode.
Bug reports and pull requests are welcome on GitHub. You can find more information about contributing in the CONTRIBUTING.md. This project is intended to be a safe, welcoming space for collaboration and discussion, and contributors are expected to adhere to the Contributor Covenant code of conduct.
This project is licensed under the MIT license.