Plumb.Readme (plumb v0.2.0)

Copy Markdown View Source

Checks that a README's install snippet still fits the version being released.

A README telling people to depend on ~> 0.1.1 when you have just published 0.2.0 is wrong in a way nothing else catches: the code compiles, the tests pass, the docs build, and everyone following the instructions silently gets the old release.

The check runs against the target version rather than the one in mix.exs, so it fails before the release is written rather than after it is published.

Modes

  • :satisfies — the target version must satisfy the requirement the README names. Imposes no style, and catches the case where a release falls outside what the README allows at all.
  • :exact — the README must name exactly ~> MAJOR.MINOR of the target. For a 0.x project, where a minor bump is a breaking change, this is the honest one: ~> 0.3 tells a reader that 0.4.0 is a safe upgrade, and it is not.

Summary

Types

mode()

Functions

check(source, app, version, mode)

Whether source is fit to publish version of app under mode.

requirement(source, app)

The requirement source names for app, from a {:app, "requirement"} pair.

Types

mode()

@type mode() :: :satisfies | :exact

Functions

check(source, app, version, mode)

@spec check(String.t(), atom(), String.t(), mode()) :: :ok | {:error, String.t()}

Whether source is fit to publish version of app under mode.

Returns :ok, or {:error, message} naming what the README says and what it should say.

Examples

iex> Plumb.Readme.check(~s|{:drafter, "~> 0.3"}|, :drafter, "0.3.1", :satisfies)
:ok

iex> Plumb.Readme.check(~s|{:drafter, "~> 0.3"}|, :drafter, "0.3.1", :exact)
:ok

requirement(source, app)

@spec requirement(String.t(), atom()) :: {:ok, String.t()} | {:error, String.t()}

The requirement source names for app, from a {:app, "requirement"} pair.

Takes the first occurrence. Returns {:error, message} when the app is not named at all, which is treated as a failure rather than a pass — a README with no install snippet cannot be verified.

Examples

iex> Plumb.Readme.requirement(~s|{:drafter, "~> 0.3"}|, :drafter)
{:ok, "~> 0.3"}