:rocket: Automatic crate publishing done right

Last update: Oct 9, 2022

Overview

semantic-rs

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.

Workflow

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.toml (also committed)
Runs cargo package for you
Creates a release on GitHub
Publishes the new version to crates.io
Done 🚀

Usage

Installation via crates.io

Ubuntu:

$ sudo apt-get install -y cmake libssl-dev pkg-config zlib1g-dev
$ cargo install semantic-rs

Prerequisites

You need the following data beforehand:

A GitHub application token Get it here
Your crates.io API key Get it here

Run it

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.

Setting GIT_COMITTER_NAME and 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.md containing everything that changed
Create a new commit containing the following changes:
- Changelog.md
- An updated Cargo.toml with 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

Development

Requirements:

cmake
OpenSSL development package
- Ubuntu: libssl-dev, pkg-config, zlib1g-dev
- Mac Homebrew: openssl
Rust 1.15 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

Build locally

Clone this project:

$ git clone [email protected]: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 cargo build. 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

Since -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.

Running the tests

To run semantic-rs's tests:

unit tests: cargo test.
integration tests: ./tests/integration/run-locally.sh.

Run semantic-rs in CI environment

Make sure to set the CI=true environment variable to disable dry-run mode.

Contributing

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.

License

This project is licensed under the MIT license.

Comments

feat: Allow write mode to be disabled, even on CI

This tackles #68.

It adds a new --no-write flag, mutually exclusive to --write. If either one is passed, we adhere to it, otherwise we determine write status based on whether CI is set or not. This allows to explicitely disable write mode on CI environments, without unsetting the variable. There is another issue now, that is we wait for other builds if CI is set, even though we know we're not gonna write (or release anything).

Should we make this "wait for CI" only in write & release mode?

opened by badboy 11
feat: Add support for major zero-style initial development

This PR adds support for major zero as outlined in http://semver.org.

Basically, breaking changes bumps the minor component and all other changes bumps the patch. Major is kept at zero.

Fixes #137.

opened by mandrean 8
GitHub release
This is a first shot at #15 and #16

[x] Push to GitHub

[x] Make sure it works on Travis with proper git key

[x] Create release on GitHub

[x] Better user key handling

[x] Publish on crates.io
opened by badboy 8
Chore: Update dependencies

This PR is smoothing the way for future features by updating a bunch of dependencies.

Note: We now require at least Rust 1.15 to compile semantic-rs. A note in the README has been made about that.

opened by schultyy 7
Handle non standard commit msg format
PR for #50

When a project does not follow the conventional commit message guidelines we default to generate a standard changelog which is not generated from commits.

TODO:

[x] Handle the case when there's already a Changelog.md. Prepend new items.

~~[ ] Pick changelog message based on version bump (Major, Minor, Fix, ...)~~ (Does not apply because after a first tag has been created we get an Unknown bump)
opened by schultyy 7
Project has no remote

PR for #73

This PR handles the case if the project has no remote configured. Before semantic-rs just failed with an error now it's printing a warning to notify the user of the things that do not happen. Since that case is not an error but something with a bit more relevance than just info the logger got a warn function for that case.

opened by schultyy 6
Add build instructions for OS X 10.11 users

Resolves #100 On OS X 10.11 the build of semantic-rs fails because of missing OpenSSL headers. To prevent the build from failure, some environment variables need to be configured.

opened by schultyy 5
Better git error

A nice and long error message and fetching the git author name the same way real git does it. I'm not 100% happy with the code and the error message could be improved as well.

opened by badboy 5

Run fails when project doesn't follow commit guidelines

Given a project where the commit message format does not follow the Angular.js commit message format. Right now execution fails with

[1] % cargo run -- -p ../test-project
     Running `target/debug/semantic-rs -p ../test-project`
semantic.rs 🚀
Analyzing your repository
Current version: 0.6.0
Analyzing commits
thread '<main>' panicked at 'called `Result::unwrap()` on an `Err` value: ParseError("Parse error")', ../src/libcore/result.rs:736
An unknown error occurred

To learn more, run the command again with --verbose.

Instead it should print out a meaningful error message.

bug

opened by schultyy 5

Problems compiling
I am currently trying to get semantic-rs to compile. I've read that the OpenSSL versions conflict so I installed the older package openssl-1.0 to make sure to compile against the right version of SSL.

Running the following command still fails though:

OPENSSL_LIB_DIR=/usr/lib/openssl-1.0 OPENSSL_INCLUDE_DIR=/usr/include/openssl-1.0 cargo install semantic-rs

At the very end I get this error message displayed. Any idea how to make semantic-rs compile?

System information

OS: Arch Linux OpenSSL version: OpenSSL 1.0.2q 20 Nov 2018 Rust version: rustc 1.33.0-nightly (14b96659e 2018-12-25) Cargo version: cargo 1.33.0-nightly (2cf1f5dda 2018-12-11)
opened by mainrs 4
Use hyper native tls

Resolves #122 and based on #118

This fixes the problem described in #122 that GitHub rejects pushes performed over http. This is caused by hyper which does not ship with its own tls implementation anymore. We fix this by including hyper-native-tls and configuring out GitHub client explicitly to use https.

opened by schultyy 4
Incorrect bump when major is v0
If a project is on, say, v0.2.0 and you have a breaking change-commit, running semantic-rs suggests the new version should now be v1.0.0:

$ semantic-rs -w=no -r=no semantic.rs 🚀 Performing preflight checks now Checks done. Everything is ok Current version: 0.2.0 Analyzing commits Commits analyzed. Bump would be Major New version would be: 1.0.0

But according to http://semver.org, you bump the 2nd component for breaking changes when you are at major v0

Expected: v0.2.0 -> v0.3.0 Actual: v0.2.0 -> v1.0.0
opened by mandrean 2
Respect publish=false for crates

There might be reasons that a crate shouldn't be published to crates.io, but still released on github (or tagged or whatever).

It's possible to tell cargo to never publish something: https://doc.rust-lang.org/cargo/reference/manifest.html#the-publish--field-optional

We should support that and not fail.
enhancement

opened by badboy 0
Extended preflight checks
We should extend our preflight checks with the following things:

Check if we have access to Crates.io (is the token valid, do we have permission to push)

Run cargo publish --dry-run so that the user has the chance to fix things before push

enhancement
opened by schultyy 0

Releases(v1.0.0)

v1.0.0(Sep 16, 2018)
v1.0.0 (2018-09-16)

Breaking Changes

Switch to using --write=yes|no (11f69f21)

dry-run by default. Overwrite by passing -w (3789d066)

Bug Fixes

remove superflous to_string() (d16a236b)

Use hyper_native_tls for GitHub interaction (a3a30a84)

we can only push if the gh_token is present (7d8f1ee3)

Updated hubcaps needs client directly (99c9048f)

indentation and error message (bbc040eb)

Does not fail when project has no remote (14edbaa3)

write repo_name to repository_name instead of user (b8235b26)

use compatible cd flag (dc69ac67)

make CDPATH assignement to empty explicit (384541e0)

restore script intention (20160882)

warnings by shellcheck && cd problem (9e12edd3)

Avoid non-POSIX readlink parameter (a3f0c9e6, closes #103)

Reorder commands to first commit, then package (63b88e0b)

Make help output consistent (773e9a42)

Switch to using --write=yes|no (11f69f21)

Only wait for other builds in release mode (19d2212f)

Handle more remote urls, like ssh (80c26341)

Use release clog version (397af709)

Wait a short time before creating the release (801d6ad3)

Do not set fixed master branch (92bfab66)

Create commit and tag against chosen branch (187d1d3f)

Push correct reference (d10b09f4)

Use uppercased env variable (3ab01ed1)

Rename it properly to CARGO_TOKEN (b969dbc6)

Handle Result returned from revwalk (01fd0271)

Canonicalize path to absolute path (5a5318fc)

Remove printed debug line (677fedf3)

Add Cargo.lock if not ignored (aa3205be)

Do not take AUTHOR into account for Git information (14ad9f03)

Properly fetch committer name and email and show helpful error message (08ea0927)

Better error when repository path was not found (7d12b177)

Commit the changelog file (51675fce)

Place changelog in repository's folder (db018f7c, closes #33)

Remove typo (d1a126d4)

Only commit Cargo.toml (f39477ba)

Exit with error code on failure (6b49489a)

Check that we're in a git repo (e7dad211)

Fail on broken Cargo.toml (6d984514)

main: Handle result of write_new_version (494b7bb1)

toml_file: Pass path to toml_file (f7f1c3f6)

Features

Fix release behavior (fc96ed12)

Replace docopt with clap (3e0fc684)

print message if everything's fine (acec3cd7)

Check if CARGO_TOKEN is defined or not (8e248bb4)

validating git remote (358154c7)

Hook preflight check into main function (c0456fcc)

Disable release mode if write mode is disabled (b58812cf)

Allow write mode to be disabled, even on CI (08c2f9f9)

adapt user message after push (6b4ec6c4)

use callback username to fetch ssh key (3ccc742e)

fetch ssh key based on email (332390ed)

Check if remote is GitHub url (3f911b58)

provide additional information for the end user (bbcff343)

performs push and github release only if there's a remote (c5e9aa0e)

add logger::warn method (6eaa6bb6)

handle the case if project doesn't have origin remote (bc5224aa)

Include and enable env_logger (916f4963)

In CI mode wait for other builds to finish (6355cc46)

Implement branch detection and abort early (934535e0)

Use Hubcaps' own std error implementation (c3b555a8)

Print nice final message (22d3f887)

Introduce special release-mode for releases on GitHub and crates.io (8c7a699f)

Fetch tokens (bb9a00eb)

Extract user and repository name from remote URL (9666341f)

Method to publish to crates.io (9601344b)

Create proper release on GitHub (67b48690)

Push new commit & tag to remote repository (47ae6dbd)

Handle IoError (d075f30a)

Make sure error messages are shown by flushing (b8806d98)

Package crate before committing (2aae1836)

Update lockfile before committing (2b1ba605)

Disable dry-run by setting CI environment variable (fe68adef)

dry-run by default. Overwrite by passing -w (3789d066)

Print generated changelog to stdout in dry-run mode (f6575055)

Check dry-run flag and act accordingly (e35d2e29)

Show semantic-rs' version (bb01b553)

Write git tag with changelog included (acbef4f5)

Create git tag after successful commit (c43212dd)

add git2-commit dependency (f6e39b68)

commit:

write new version in commit message (21c11855)

Commit updated Cargo.toml and Cargo.lock (15682f32)

main: Allow the user to pass a custom path to a repository (ce2dd516)

Source code(tar.gz)
Source code(zip)