Release checklist for rust crates

Release when ready, release frequently. Essentially means each cycle of conception to completion shall be short and the cycles themself shall repeated often. Following is a checklist of things todo before making a release.

Rust crates come in two form, executable-binary and library.

Release checklist for rust library

• Look for TODO comments and todo!() macros, move them to issues or just collect them in a separte TODO.md file under repository root.
• Review macros - println!(), panic!(), unreachable!(), unimplemented!(). Make sure they are obsolute necessary. Preferably replace println!() with log facade.
• Check for dead_code.
• Check for ignore test cases and if present add them to CI.
• Cleanup unwanted fmt::Debug and fmt::Display traits from types.
• Remove trait constraints on type and implementations, as much as possible.
  • Use MaybeUninit, instead of Default.
  • Use move-semantics instead of Copy and Clone traits.
  • Reduce the function specific trait constraints to function-signatures.
  • Combine functions with common trait constraits into single impl{}.
• Replace assert!() with Error return or debug_assert!().
• Calls to unwrap()/expect() can panic. Make sure the panic is intended, preferrabley replace unwrap() with expect() call.
• Review ok() method on Result and Option types. They silently ignore errors.
• "as" type casting is dangerous. Replace them with try_into() or try_from() call.
• Review unsafe { .. } blocks and document them.
• README.md must be present, and shall contains
  • Link to rust-doc.
  • Short description.
  • Useful links.
  • Contribution guidelines.
• Check for possible upgrades to required crates.
• Check for LICENSE compatibility.
• Makefile, the g(old)en simplicity from yester-years. All the make targets shall pass with 0 warnings and 0 errors.
  • clean target, remove file created by CI scripts.
  • build target, follow the build matrix and add them under this target.
  • prepare target, run the continuous-integration scripts as part of release preparation.
  • flamegraph target, to generate flamegraph using cargo-flamegraph
  • spellcheck target, to check for spelling mistakes in rustdoc using carg-spellcheck
• Documentation Review.
• Add COPYRIGHT and LICENSE, as applicable.
• Add release notes in RELEASE.md.
• Bump up the version:
  • major: backward incompatible API changes.
  • minor: backward compatible API Changes.
  • patch: bug fixes.
• If CI is setup, then make sure that latest commit upto release preperation has passed.
• Create a git-tag for the new version.
• Cargo publish the new version.

We may have to install cargo-flamegraph and cargo-spellcheck via cargo install command.

Declare for

Wherever applicable declare a library for the following features.

• Zero heap allocations.
• Zero dependencies.
• No-panic.
• No-unsafe.
• Depth-limited recursion (or) No-recursion.
• no_std compatible.
• WASM compatible.

Project layout

• Cargo.toml, cargo manifest file.
• check.sh, CI script for testing.
• LICENSE
• Makefile, CI script.
• perf.sh, CI script for benchmark and perf-measurements.
• README.md
• RELEASE.md, release notes for each release.
• rustfmt.toml, configuration for rustfmt.
• src, library
  • src/bin, binary-tools to support/work-with library artifacts.
• TODO.md

This is based on cargo’s recommended project-layout.

Build matrix

	build	test	bench	doc	clippy
stable-dev	✓	✓
stable-release	✓	✓	✓	✓	✓
nightly-dev	✓	✓
nightly-release	✓	✓	✓	✓	✓

Rustfmt

Following is my general preference for rust-fmt.

max_width = 90