preparation for release (#35)

Cargo.toml

@@ -10,7 +10,7 @@ license = "MIT/Apache-2.0"
 name = "vergen"
 readme = "README.md"
 repository = "https://github.com/rustyhorde/vergen"
-version = "3.2.0"
+version = "4.0.0"
 
 [features]
 default = ["build", "git", "rustc"]
@@ -21,12 +21,12 @@ rustc = ["rustc_version"]
 [dependencies]
 bitflags = "1"
 chrono = { version = "0", optional = true }
+enum-iterator = "0"
 getset = "0"
 git2 = { version = "0", optional = true }
 rustc_version = { version = "0", optional = true }
 serde = "1"
 serde_derive = "1"
-enum-iterator = "0.6.0"
 
 [build-dependencies]
 chrono = "0"

README.md

@@ -4,6 +4,40 @@
 [![Crates.io](https://img.shields.io/crates/l/vergen.svg)](https://crates.io/crates/vergen)
 [![Crates.io](https://img.shields.io/crates/d/vergen.svg)](https://crates.io/crates/vergen)
 
+## Release 4.0 Breaking Changes
+* The main entry point for use has changed from `generate_cargo_keys` to `gen`
+* There are now 3 features that allow you to control what instructions can be generated (`build`, `git`, and `rustc`).
+    * The `build` feature enables the `VERGEN_BUILD_*` instructions.
+    * The `git` feature enables the `VERGEN_GIT_*` instructions, the `cargo:rerun-if-changed` instructions, and the `REBUILD_ON_HEAD_CHANGE` flag.
+    * The `rustc` feature enables the `VERGEN_RUSTC_*` instructions.
+    * By default, all three features are enabled.
+    * You can build with all three features disabled, which basically make the `gen` function a no-op.
+    * You can still use `ConstantsFlags` to toggle individual cargo instructions.
+* The generated instructions have been normalized.  Therefore, you may need to update what env variable you are referring to in code.  I've included a list below of the full set of instructions that can be generated for reference.
+
+```text, no_run
+cargo:rustc-env=VERGEN_BUILD_DATE=2021-02-12
+cargo:rustc-env=VERGEN_BUILD_TIMESTAMP=2021-02-12T01:54:15.134750+00:00
+cargo:rustc-env=VERGEN_GIT_BRANCH=feature/git2
+cargo:rustc-env=VERGEN_GIT_COMMIT_DATE=2021-02-11T20:05:53-05:00
+cargo:rustc-env=VERGEN_GIT_SEMVER=v3.2.0-86-g95fc0f5
+cargo:rustc-env=VERGEN_GIT_SEMVER_LIGHTWEIGHT=blah-33-g95fc0f5
+cargo:rustc-env=VERGEN_GIT_SHA=95fc0f5d066710f16e0c23ce3239d6e040abca0d
+cargo:rustc-env=VERGEN_GIT_SHA_SHORT=95fc0f5
+cargo:rustc-env=VERGEN_RUSTC_CHANNEL=nightly
+cargo:rustc-env=VERGEN_RUSTC_COMMIT_DATE=2021-02-10
+cargo:rustc-env=VERGEN_RUSTC_COMMIT_HASH=07194ffcd25b0871ce560b9f702e52db27ac9f77
+cargo:rustc-env=VERGEN_RUSTC_HOST_TRIPLE=x86_64-apple-darwin
+cargo:rustc-env=VERGEN_RUSTC_LLVM_VERSION=11.0
+cargo:rustc-env=VERGEN_RUSTC_SEMVER=1.52.0-nightly
+cargo:rerun-if-changed=/Users/yoda/projects/rust-lang/vergen/.git/HEAD
+cargo:rerun-if-changed=/Users/yoda/projects/rust-lang/vergen/.git/refs/heads/feature/git2
+```
+
+* Under the hood, the `Command`s used for git have been removed in lieu of using the `git2` library directly.
+* `git2` is also used to determine the `HEAD` path and the path that it refers to for the `cargo:rerun-if-changed` instructions.  This is more reliable then the manual method that was in place before.
+* I've migrated the CI stuff from Travis to GitHub Actions.
+
 ## Build Status
 ![CI](https://github.com/rustyhorde/vergen/workflows/CI/badge.svg)
 

src/lib.rs

@@ -85,7 +85,12 @@
 //! 1. [`git2::Repository::describe`]
 //! 2. [`CARGO_PKG_VERSION`]
 //!
-//! By default, if the `git` feature is enabled semver generation will use the first method.  If the `git` feature is disabled or method one errors, generation falls back to the second method.
+//! By default, if the `git` feature is enabled semver generation will use the first method.
+//! If the `git` feature is disabled or method one errors, generation falls back to the second method.
+//! Note that the `git describe` method is only useful if you have tags on your repository.
+//! I recommend [`SemVer`] tags, but this will work with any tag format.
+//! If your repository has no tags, this method will always fall back to [`CARGO_PKG_VERSION`].
+//! Also worth noting, `VERGEN_SEMVER` and `VERGEN_SEMVER_LIGHTWEIGHT` will only differ if you use [lightweight] tags in your repository.
 //!
 //! If you wish to force method two even if the `git` feature is enabled you may toggle off [`SEMVER`] and toggle on [`SEMVER_FROM_CARGO_PKG`].
 //!
@@ -102,6 +107,8 @@
 //! [build scripts]: https://doc.rust-lang.org/cargo/reference/build-scripts.html
 //! [cargo:rustc-env]: https://doc.rust-lang.org/cargo/reference/build-scripts.html#rustc-env
 //! [cargo:rerun-if-changed]: https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed
+//! [lightweight]: https://git-scm.com/book/en/v2/Git-Basics-Tagging
+//! [SemVer]: https://semver.org/
 //!
 #![deny(
     absolute_paths_not_starting_with_crate,