Package Style

This package style guide is based on the one made by KISS Community, with a few changes for readability, leniency, and slight differences between kiss and gel.

[0100]: Blacklisted Packages

The following package types are not allowed in the repository:

  • git packages
  • Obscure programs
  • Packages with known severe security vulnerabilities, unless there is a patch that fixes it.
  • Packages depending on systemd, unless there is a patch or service that removes the dependency.
  • Binaries for small programs

[0200]: Package Naming

Large packages with a large dependency count (especially Desktop Environments) should be given their own repository.

Binary packages should be suffixed with -musl-bin or -glibc-bin.

Packages should have all-lowercase names, and should avoid the characters +=/`.,?_ and all whitespace.

Shebang

When using a script, these rules must be followed.

[0300]: Formatting

Include a blank line below all shebangs:

#!/bin/sh -ex

# ...

[0400]: Compatibility

  • Always use #!/bin/sh as the build script shell.
  • The build, pre-remove, and post-install files must all pass through shellcheck with no warnings. Disable warnings if necessary.

[0500]: Error-checking

Use the -ex flags on shell shebang: #!/bin/sh -ex

Comments

The following guidelines should be followed when commenting in any package files.

[0800]: Grammar

Comments must use semi-formal grammar (avoid slang, but colloquialisms are allowed) and correct spelling, but are not required to have end punctuation (please use commas) nor a capital letter at the beginning.

# this is a comment

[0900]: Purpose

Comments should explain why something is being done, not what it is doing:

# `make install` doesnt create the directory
mkdir -p "$1/usr/bin"

Commit Messages

Commit messages must conform to the following rules.

[1000]: New Packages

Use the following commit message format when creating a package:

new package: [package] [version]

Use the following commit message format when updating a package:

[package]: update to [version]

[1100]: Commit Count

Each package should only have one commit on each modification (creation or updating). If a package requires corrections, the package should be rebased or have commits locally reversed and forcefully pushed.

Another possible option is having a maintainer close a pull request, recreate it locally with one commit message, and push it. If this route is taken, a comment such as "Manually merged in commit " should be written under the pull request.

Quotes

When quoting variables, the following rules should be followed.

[1200]: Only use quotes when necessary

Avoid using quotes when unnecessary:

# `build/bin/foo` does not need to be quoted
cp "build/bin/foo" "$1/usr/bin"

For reference, the above should be rewritten as:

cp build/bin/foo "$1/usr/bin"

[1300]: Quote formatting

Quote entire strings to insert a variable:

cp -f cat "$1/usr/bin/cat"

Unless it is being used to set a flag requiring an equals sign:

make DESTDIR="$1" install

Command Formatting

[1400]: Command Choice

Prefer cp and mkdir over install:

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

When using install, note the BSD syntax and GNU syntax differ.

[1500]: Directory formatting

Do not end directories in a slash.

# Bad:
cp foo "$1/usr/bin/"

# Good:
cp foo "$1/usr/bin"

[1600]: Build tool formatting

When using a command such as make, create a new line with \ if more than two variables or flags are being provided (excluding the operation itself).

Place the operation after the flags, unless you split the command across multiple lines.

# Bad:
make CC="$CC" DESTDIR="$1" PREFIX="/usr" install

# Good:
make install \
    CC="$CC" \
    DESTDIR="$1" \
    PREFIX="/usr"

# Bad:
meson build --no-tests

# Good:
meson --no-tests build

# Bad:
make all \
    ENABLE_FOO=yes \
    ENABLE_BAR=yes

# Good:
make ENABLE_FOO=yes ENABLE_BAR=yes no all