style-guide.txt

PACKAGE STYLE GUIDE
________________________________________________________________________________

This document is a style guide which will double as documentation for a possible
package linter in the future. Every package in the Official Repositories and the
Community repository adheres to this style guide.

NOTE: Exceptions are made where it makes sense.


MAINTAINERSHIP
________________________________________________________________________________

* Each package has a set maintainer stored via git commits. Use 'git log' or
  'kiss-maintainer pkg' to find the maintainer's contact information.

* Only the maintainer of a package has the ability to make changes to said
  package. Any pull requests by a non-maintainer for a package will be closed.

* If you would like to make a change to an existing package, contact the
  maintainer and they will do so on your behalf.

* If the maintainer leaves a package out of date and does not respond in a
  reasonable time frame, the package will be orphaned and up for grabs.

* If no one steps forward to adopt an orphaned package, it will be dropped from
  the repositories.


GENERAL
________________________________________________________________________________


    [0000]----------------------------------------------------------------------

    Package is not suitable for inclusion in the Community repository. The same
    rules above may apply to other software at the discretion of the BDFL.

    Examples: ConsoleKit, dbus, electron, gettext, gtk2, intltool, libsn,
              logind, pam, pipewire, polkit, pulseaudio, systemd, wayland and
              all Desktop Environments.


    [0001]----------------------------------------------------------------------

    No new packages shall use Python 2 as it will be removed once Chromium drops
    it as a dependency.


    [0002]----------------------------------------------------------------------

    Packages which are binaries should contain the suffix '-bin' to reflect
    this fact. Similarly, packages which pull from git should contain the
    suffix '-git'. The version of git packages should also be set to 'git'.



BUILD
________________________________________________________________________________


    [0200]----------------------------------------------------------------------

    This guide should be used alongside shellcheck and not in place of it.


    [0201]----------------------------------------------------------------------

    All shell code must pass the shellcheck linter. Any false-positives or
    intended behavior must have a rationale attached with the exclusion.

    # Disable warning as CFLAGS must work this way.
    # shellcheck disable=2086
    "${CC:-cc}" $CFLAGS ...


    [0202]----------------------------------------------------------------------

    Use 4 spaces for indentation.


    [0203]----------------------------------------------------------------------

    Lines should not exceed 80 characters in length.


    [0204]----------------------------------------------------------------------

    All packages must use the POSIX shell shebang with '-e' to exit on error.
    Additionally, '-ef' can be used if word-splitting is required.

    There must also be a blank line directly below the shebang.

    #!/bin/sh -e

    # Code starts here.


    [0205]----------------------------------------------------------------------

    All comments must start with a capital letter and use proper spelling,
    grammar and punctuation.

    # This is a comment.


    [0206]----------------------------------------------------------------------

    Leave comments to explain *why* the code is needed and not *what* it does.

    Bad:

    # Create a directory.
    mkdir -p "$1/usr/bin"

    Good:

    # 'make install' doesn't create the directory.
    mkdir -p "$1/usr/bin"


    [0207]----------------------------------------------------------------------

    Avoid adding braces around variables if unneeded.

    Bad:  printf '%s\n' "${var}"
    Good: printf '%s\n' "$var"
    Good: printf '%s\n' "${var}.${var2}"


    [0208]----------------------------------------------------------------------

    Avoid quotes when unneeded.

    Bad:  [ "$var" = "test" ]
    Good: [ "$var" = test ]

    Bad:  install -Dm755 "file" "$1/usr/bin/file"
    Good: install -Dm755 file "$1/usr/bin/file"


    [0209]----------------------------------------------------------------------

    Quote entire strings instead of variables.

    Bad:  install -Dm644 cat "$1"/usr/bin/cat
    Good: install -Dm644 cat "$1/usr/bin/cat"


    [0210]----------------------------------------------------------------------

    Align arguments in blocks of command calls.

    Bad:

    install -D file.h "$1/usr/include/file.h"
    install -D libfile.so "$1/usr/lib/libfile.so"

    Good:

    install -D file.h     "$1/usr/include/file.h"
    install -D libfile.so "$1/usr/lib/libfile.so"


    [0211]----------------------------------------------------------------------

    Use 'install' instead of ...

    Bad:

    mkdir -p "$1/usr/bin"
    cp ls "$1/usr/bin/"

    Good:

    install -Dm755 ls "$1/usr/bin/ls"


    [0212]----------------------------------------------------------------------

    Prefer $CC to ...

    Bad:  gcc -o file file.c
    Good: "${CC:-cc}" -o file file.c


    [0213]----------------------------------------------------------------------

    Always use '-p' with 'mkdir'.



GNU AUTOTOOLS
________________________________________________________________________________


    [0400]----------------------------------------------------------------------

    Use the following style:

       ./configure \
           --prefix=/usr \
           --more_args_here

       make
       make DESTDIR="$1" install


    [0401]----------------------------------------------------------------------

    Avoid running ./autogen.sh, autoreconf or similar tools prior to starting
    the build process. If there are no pre-generated configure or Makefiles, an
    alternate source must be sought.

    An exception can be made for packages in which no such source exists. If
    autogen.sh or autoreconf are required, prefer autoreconf.



MESON
________________________________________________________________________________


    [0600]----------------------------------------------------------------------

    Use the following style:

       export DESTDIR="$1"

       meson \
           --prefix=/usr \
           -Dexample=false \
           . output

       ninja -C output
       ninja -C output install



CMAKE
________________________________________________________________________________


    [0800]----------------------------------------------------------------------

    Use the following style:

       export DESTDIR="$1"

       cmake -B build \
           -DCMAKE_INSTALL_PREFIX=/usr \
           -DFLAG=1

       cmake --build   build
       cmake --install build



MAKE
________________________________________________________________________________


    [1000]----------------------------------------------------------------------

    Use one of the following style when applicable:

       make
       make DESTDIR="$1" PREFIX=/usr install


       make PREFIX=/usr
       make DESTDIR="$1" install


       make PREFIX=/usr
       make DESTDIR="$1" PREFIX=/usr install


    For packages which require a few variables be set, prefer this style.

       make \
           PREFIX=/usr \
           SBINDIR=/usr/bin \
           OPT="$CFLAGS"

       make \
           DESTDIR="$1" \
           PREFIX=/usr \
           install


    For packages which require the variables be set for all calls to make,
    prefer this style.

       mk() {
           make \
               PREFIX=/usr \
               DESTDIR="$1" \
               EXAMPLE=1 \
               "$@"
       }

       mk
       mk install



RUST
________________________________________________________________________________


    [1050]----------------------------------------------------------------------

    Use the following style:

       cargo build --release

       install -Dm755 target/release/rg "$1/usr/bin/rg"



GO
________________________________________________________________________________


    [1100]----------------------------------------------------------------------

    Use the following style:

       export GOPATH="$PWD/go"
       export GO111MODULE=on

       go build \
           -modcacherw \
           -trimpath

       install -Dm755 lazygit "$1/usr/bin/lazygit"

    Note: If the directory 'vendor' is available in the root directory of the
    source, the preffered method is to omit GOPATH and GO111MODULE and use:

        go build \
            -mod=vendor \
            -further-options

    to prevent cluttering $HOME and enable offline building.

PYTHON
________________________________________________________________________________


    [1150]----------------------------------------------------------------------

    Use the following style:

       python setup.py build
       python setup.py install --prefix=/usr --root="$1"



DEPENDS
________________________________________________________________________________


    [1201]----------------------------------------------------------------------

    This dependency is unneeded and can be removed.


    [1202]----------------------------------------------------------------------

    This dependency is implicit. Some packages are assumed to always be
    available. This dependency can be removed.

    Examples: gcc, make, musl.


    [1203]----------------------------------------------------------------------

    This dependency needs 'make' as it is only required during build time.

    Common Examples: autoconf, automake, cmake, meson.


    [1204]----------------------------------------------------------------------

    This dependency doesn't need 'make' as it is required during runtime.


    [1205]----------------------------------------------------------------------

    The depends list must be sorted.


    [1206]----------------------------------------------------------------------

    The depends file is empty and should be removed.



SOURCES
________________________________________________________________________________


    [1401]----------------------------------------------------------------------

    Use a HTTPS source if at all possible.


    [1402]----------------------------------------------------------------------

    Don't specify patches remotely. Store them as a part of the package's
    repository files.

    Bad:  https://example.com/fix-build.patch
    Good: patches/fix-build.patch


    [1403]----------------------------------------------------------------------

    Don't use a git repository in place of a release tarball unless it makes
    sense to do so.


    [1404]----------------------------------------------------------------------

    Drop www. and .git from all sources if possible.



VERSION
________________________________________________________________________________


    [1601]----------------------------------------------------------------------

    Version doesn't match upstream.


    [1602]----------------------------------------------------------------------

    Use 'git' in place of '9999'.


    [1603]----------------------------------------------------------------------

    Missing relative version number.

    Bad:  1.0.0
    Good: 1.0.0 1



PATCHES
________________________________________________________________________________


    [1800]----------------------------------------------------------------------

    Use the following style:

         patch -p1 < patch.patch

         # If there is more than one patch.
         for patch in *.patch; do
             patch -p1 < "$patch"
         done


    [1801]----------------------------------------------------------------------

    All patches should use the same strip amount. If this is not possible,
    modify the patches. Strip amount is controlled by the -p flag.