Avoid
.rst
extensions for files designed to be read directly (such asREADME.rst
).If the file declares file format in the vim modeline (e.g.
vim:ft=rst
), GitHub no longer requires the extension to render the file correctly.- Avoid
.txt
extensions for files designed to be read directly. doc/README
should briefly describe the project.- There should be
README
→doc/README
symlink. - The
README
symlink should not shipped in release tarballs. - Validate reStructuredText documents with
rst2xml --strict
. - Validate POD documents with
podchecker
. - DocBook XML documents should be avoided.
- Validate legacy DocBook XML documents with
xmllint --valid
. - Check URLs using urlycue.
- Check that version numbers in documentation and in the code match.
- Manual pages should include version numbers.
- Manual page dates should be up-to-date.
- English manual page dates should be in the YYYY-MM-DD format. Manual pages must not use a middle-endian date format.
- In manual pages:
- apostrophes should be written as
'
, not\(aq
; - hyphens should be written as
-
; - minus-signs should be written as
\-
.
- apostrophes should be written as
rst2man
calls should use--input-encoding=UTF-8
.- Built manual pages should not include vim modelines.
- Check that the changelog is complete.
- In repo, there should be top-level
LICENSE
(orCOPYING
) file. - In release tarballs,
LICENSE
(orCOPYING
) should be moved to thedoc
subdirectory. - Copyright notices should be up-to-date.
GPLv2 files should carry the following license notice:
This file is part of PROJECT.
PROJECT is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.
PROJECT is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
- Autoconf-based packages should provide the
private/autogen
andprivate/autoclean
scripts. - The name of Autoconf configuration header files should be
autoconf.h
(or similar). autoconf
should fail when 3rd-party macros are missing, e.g.:m4_pattern_forbid( [^PKG_CHECK_MODULES], [undefined macro PKG_CHECK_MODULES; install pkg-config and run private/autogen] )
- Check if all the files (binaries, manual pages) are installed correctly.
- Use
perl -pi
(rather thansed -i
) for in-place edits. - Don't assume
install
is GNU install. Don't useinstall -D
because GNU install does something entirely different that FreeBSD install. - Makefiles can require GNU make, but then they should fail with helpful error when run against BSD make.
- Check Python code with pydiatra.
- Check Python code with pyflakes.
- Check Python code with pylint.
- Python modules should have sensible
__all__
. - Validate module long description with
rst2xml --strict
. - Don't assume that the Python interpreter is at
/usr/bin/python
. setup.py
should not import any code from the source tree.- Check Python version at runtime.
- Check Python version at install time.
- Byte-compile source at install time.
- Check Perl code with perlcritic.
- Every Perl script should start with
no lib '.';
as a defence against CVE-2016-1238. - Don't assume that the Perl interpreter is at
/usr/bin/perl
.
- Check shell scripts with shellcheck.
- Shell scripts should use
set -e
. - Shell scripts should use
set -u
. - Use
command -v
, notwhich
.
- LFS build flags should be enabled.
- Environment variables such as
CC
,CFLAGS
, etc. should be honored. CFLAGS
should be honored when linking (so that-fsanitize=address
etc. work).- Check code with cppcheck.
- Use
tiparm()
instead oftparm()
.
The
--version
option should print to stdout, not stderr.Note that in Python prior to 3.4,
argparse
doesn't do it correctly out of the box: https://bugs.python.org/issue18920- The
--version
option should print versions of most important underlying libraries. - Exit status for
--version
should be 0. - The
--help
option should print to stdout, not stderr. - Exit status for
--help
should be 0. - Programs that produce copious amount of output (and do nothing else besides that) should have default signal handler for
SIGPIPE
. Programs should catch exceptions that could be caused by typical user or environment errors (e.g., a file cannot be opened).
There should be command-line option to let these exceptions go through.
- Coverage file should be up to date.
- There should be an easy way to run the tests against installed package.
- Files should have sane ownership (
root:root
) and permissions (0644 or 0755). - Directory entries should be sorted. (For GNU tar, use
--sort=name
.) - The POSIX 1003.1-1988 (ustar) format should be used.
- Tarballs should be compressed with
gzip -9n
. - XZ compression can be used if it would save at least 64 KiB.
- For XZ compression, the least memory-intensive preset that still offers optimal file size should be used. The
-e
option should be used.
- Most items in
.gitignore
and.gitattributes
should be anchored with/
.
- When possible, the above checks should be automated using CI.