Documentation

• Avoid .rst extensions for files designed to be read directly (such as README.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 \-.

• rst2man calls should use --input-encoding=UTF-8.

• Built manual pages should not include vim modelines.

• Check that the changelog is complete.

Copyright

• In repo, there should be top-level LICENSE (or COPYING) file.

• In release tarballs, LICENSE (or COPYING) should be moved to the doc 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.

Spelling

• Check spelling with mwic.
• Check spelling with anorack.

Build system

• Autoconf-based packages should provide the private/autogen and private/autoclean scripts.
• The name of Autoconf configuration header files should be autoconf.h (or similar).
• Environment variables such as CC, CFLAGS, etc. should be honoured.
• Check if all the files (binaries, manual pages) are installed correctly.

Portability

• Use perl -pi (rather than sed -i) for in-place edits.
• Don't assume install is GNU install. Don't use install -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.

Python code

• 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.

Perl code

• 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.

Shell scripts

• Check shell scripts with shellcheck.
• Shell scripts should use set -e.
• Shell scripts should use set -u.
• Use command -v, not which.

C code

• LFS build flags should be enabled.
• CFLAGS should be honored when linking (so that -fsanitize=address etc. work).
• Check code with cppcheck.
• Use tiparm() instead of tparm().

CLI

• 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.

Tests

• Coverage file should be up to date.
• There should be an easy way to run the tests against installed package.

Release tarballs

• 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.

VCS

• Most items in .gitignore and .gitattributes should be anchored with /.

Continuous integration

• When possible, the above checks should be automated using CI.