[ANN] QCheck 0.90: The Great Renaming

Community
, ,
1

It is my pleasure to announce release 0.90 of the QCheck packages. QCheck is an
OCaml library for randomized property-based testing in the style of Haskell’s
QuickCheck.

Release 0.90 · c-cube/qcheck · GitHub

It has been over 12 years and 40 releases since @c-cube released version 0.1
back in October 2013. Over this period QCheck has grown organically

  • with new combinators on a “by-need” basis and
  • with a separate QCheck2 module offering generators with integrated shrinking.

This has unfortunately resulted in a bit of a naming mess with inconsistent
generator names. For example, the (now deprecated) small_int combinator will
generate only small non-negative numbers, and a combinator for generating
positive integers uniformly is named either pint or pos_int across different
QCheck modules.

The 0.90 release thus takes on a cleanup under the heading “The Great Renaming”.
To guide the renaming process, we have assembled a list of hard-learned
naming principles:

  • Generator names should align with type names (bool, char, … list, option) to be as predictable as possible
  • We should have short, unparameterized generators (int, string, …) to lower the barrier to entry
  • Specialized generators also start with the type name, but use a consistent suffix (_pos, _neg, _size, _of, …) to help find them, e.g., with tab-completion
  • We may include a few shorthand names for convenience (e.g., nat)
  • Overall we aim to be as consistent as possible, e.g., offering similar signatures
    across generator interfaces (QCheck.Gen, QCheck.arbitrary, and QCheck2.Gen)

The 0.90 release thus both

  • introduces a range of new (and hopefully more consistent) combinator names and
  • deprecates a sizable number of old, inconsistent combinator names

The deprecated combinators have been annotated with @@deprecated attributes.

Rather than let a couple more years pass with an even bigger and more confusing
name pool, we are using this opportunity to prepare a long overdue 1.0.0
release, where we will remove the old, deprecated combinator names.

We understand that updating existing tests to the new names takes some effort, but appeal to
users that this should be a one-time investment to

  • offer more consistent and easier to recall combinator names and simultaneously
  • let us clean up QCheck tech debt and address a long-time pain point.

The changes are summarized in a record-long CHANGELOG section for the release:

qcheck/CHANGELOG.md at v0.90 · c-cube/qcheck · GitHub

and c-cube/qcheck#366 provides a run down of the renaming process.

For more details, see the following list of PRs:

Finally, on behalf of the maintainers I would like to thank

  • the various folks contributing to QCheck over the past 12 years and
  • the OCaml Software Foundation for financially supporting the work on these
    past three releases.

Merry Christmas and happy testing! :evergreen_tree: :wrapped_gift:

12 Likes