RFC: New pkglint warning for Makefile.common

[Roland Illig <rillig%NetBSD.org@localhost>]

Hi,

some months or even years ago, there was a discussion about comments in 
Makefile.common files that say which files are including them. Because 
the Makefile.common often don't have a particular purpose (as opposed to 
plugin.mk or module.mk or the like), they usually don't include any 
documentation about what they do and what's the proper way of using them.

When updating such a package or modifying Makefile.common, one has to 
search the whole pkgsrc tree for files that use the Makefile.common, and 
in some cases this cannot be guessed by the package names alone. For 
example, x11/labltk/Makefile uses lang/ocaml/Makefile.common, which was 
a little surprise for me, because the former doesn't have a name related 
to OCaml.

Therefore, I wrote a bit of code that prints the following warning:

$ pkglint -e x11/labltk
WARN: x11/labltk/../../lang/ocaml/Makefile.common:3: \
        Please add a line "# used by x11/labltk/Makefile" here.

        Since Makefile.common files usually don't have any comments and
        therefore not a clearly defined interface, they should at least
        contain references to all files that include them, so that it is
        easier to see what effects future changes may have.

        If there are more than five packages that use a Makefile.common,
        you should think about giving it a proper name (maybe plugin.mk)
        and documenting its interface.

Do you find this warning useful? Unnecessary? Whatever?

Roland