Commit 165b6a05 authored by Herbert Valerio Riedel's avatar Herbert Valerio Riedel 🕺 Committed by GitHub
Browse files

New `cabal check` to warn about suspiciously short descriptions (#3479)

It seems that package authors are often unaware of the purpose of
synopsis/description fields, and their impact on cabal and Hackage.  A
common mistake is to write a verbose synopsis and leave the description
field empty or even worse with useless boilerplate-text filled in by
tooling, resulting in a suboptimal presentation on Hackage.

The `synopsis` is supposed to be a terse <80 char description. In fact,
the cabal user's guide states:

> A very short description of the package, for use in a table of
> packages. This is your headline, so keep it short (one line) but as
> informative as possible. Save space by not including the package name
> or saying it’s written in Haskell.

On Hackage this synopsis is printed in the `<title>` and at the top of the
package page, and is difficult to spot. However, the synopsis is
displayed on Hackage in package lists or search results.

On the other hand, the `description` field is rather important for
`cabal info`  as well as the package cover-page, as it's printed below
the "The $PKGNAME package"-heading, and above the properties section,
and that's where everyone looks at.

This new lint check is an attempt to point out a suspiciously short
description field by using the heuristic of expecting the description
field to be longer than the synopsis.
parent f357f778
......@@ -449,6 +449,22 @@ checkFields pkg =
PackageDistSuspicious
"The 'synopsis' field is rather long (max 80 chars is recommended)."
-- See also https://github.com/haskell/cabal/pull/3479
, check (not (null (description pkg))
&& length (description pkg) <= length (synopsis pkg)) $
PackageDistSuspicious $
"The 'description' field should be longer than the 'synopsis' "
++ "field. "
++ "It's useful to provide an informative 'description' to allow "
++ "Haskell programmers who have never heard about your package to "
++ "understand the purpose of your package. "
++ "The 'description' field content is typically shown by tooling "
++ "(e.g. 'cabal info', Haddock, Hackage) below the 'synopsis' which "
++ "serves as a headline. "
++ "Please refer to <https://www.haskell.org/"
++ "cabal/users-guide/developing-packages.html#package-properties>"
++ " for more details."
-- check use of impossible constraints "tested-with: GHC== 6.10 && ==6.12"
, check (not (null testedWithImpossibleRanges)) $
PackageDistInexcusable $
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment