commit 6a658833babeacfae4eea7cbcad61c3a817d178d
parent 12891dbd137f45d6357a2dd972ec3a2e342402d3
Author: phoebos <ben@bvnf.space>
Date: Mon, 7 Aug 2023 13:11:46 +0100
kiss/style-guide: index
Diffstat:
3 files changed, 524 insertions(+), 29 deletions(-)
diff --git a/label.awk b/label.awk
@@ -0,0 +1,30 @@
+#!/usr/bin/awk -f
+# For articles with only h2 and h3 as major and minor headings.
+# If there is a ## Index already present, run with `awk -v major=-1`.
+# You must manually move the index to the top.
+
+BEGIN { li = 0 }
+
+/^## / {
+ printf("## %%[%s]\n", substr($0, 4))
+ labels[li,0] = substr($0, 4)
+ labels[li++,1] = 1
+ next
+}
+/^### / {
+ printf("### %%[%s]\n", substr($0, 5))
+ labels[li++,0] = substr($0, 5)
+ next
+}
+{
+ print
+}
+
+END {
+ printf("\n## Index\n\n")
+ for (i=0; i < li; i++) {
+ if (labels[i,1] != 1)
+ printf(" ");
+ printf("- [%s](#%s)\n", labels[i,0], labels[i,0]);
+ }
+}
diff --git a/wiki/kiss/style-guide/index.md b/wiki/kiss/style-guide/index.md
@@ -7,9 +7,25 @@ Community repository adheres to this style guide.
NOTE: Exceptions are made where it makes sense.
-
-MAINTAINERSHIP
---------------
+## Index
+
+- [MAINTAINERSHIP](#MAINTAINERSHIP)
+- [GENERAL](#GENERAL)
+- [BUILD](#BUILD)
+ - [GNU AUTOTOOLS](#GNU AUTOTOOLS)
+ - [MESON](#MESON)
+ - [CMAKE](#CMAKE)
+ - [MAKE](#MAKE)
+ - [RUST](#RUST)
+ - [GO](#GO)
+ - [PYTHON](#PYTHON)
+- [DEPENDS](#DEPENDS)
+- [SOURCES](#SOURCES)
+- [VERSION](#VERSION)
+- [PATCHES](#PATCHES)
+
+
+## %[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.
@@ -27,8 +43,7 @@ MAINTAINERSHIP
the repositories.
-GENERAL
--------
+## %[GENERAL]
%[0000]
@@ -50,8 +65,7 @@ suffix '-git'. The version of git packages must also be set to 'git'.
-BUILD
------
+## %[BUILD]
%[0200]
@@ -193,8 +207,7 @@ Always use `printf`. Do not use `echo`.
-GNU AUTOTOOLS
--------------
+### %[GNU AUTOTOOLS]
%[0400]
@@ -220,8 +233,7 @@ autogen.sh or autoreconf are required, prefer autoreconf.
-MESON
------
+### %[MESON]
%[0600]
@@ -240,8 +252,7 @@ Use the following style:
-CMAKE
------
+### %[CMAKE]
%[0800]
@@ -259,8 +270,7 @@ Use the following style:
-MAKE
-----
+### %[MAKE]
%[1000]
@@ -308,8 +318,7 @@ prefer this style.
-RUST
-----
+### %[RUST]
%[1050]
@@ -322,8 +331,7 @@ Use the following style:
-GO
---
+### %[GO]
%[1100]
@@ -348,8 +356,7 @@ source, the preferred method is to omit GOPATH and GO111MODULE and use:
to prevent cluttering $HOME and enable offline building.
-PYTHON
-------
+### %[PYTHON]
%[1150]
@@ -361,8 +368,7 @@ Use the following style:
-DEPENDS
--------
+## %[DEPENDS]
%[1201]
@@ -401,8 +407,7 @@ If depends file is empty, then it must be removed.
-SOURCES
--------
+## %[SOURCES]
%[1401]
@@ -431,8 +436,7 @@ Drop www. and .git from all sources if possible.
-VERSION
--------
+## %[VERSION]
%[1601]
@@ -454,8 +458,7 @@ The version file must contain relative version number.
-PATCHES
--------
+## %[PATCHES]
%[1800]
diff --git a/wiki/kiss/style-guide/index.md.in b/wiki/kiss/style-guide/index.md.in
@@ -0,0 +1,462 @@
+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]
+
+Some packages are not suitable for inclusion in the Community repository.
+
+Examples: ConsoleKit, dbus, electron, gettext, gtk2, intltool, libsn,
+logind, pam, python2, polkit, pulseaudio, systemd and all Desktop Environments.
+
+The same rules above may apply to other software at the discretion of
+maintainers.
+
+
+%[0001]
+
+Packages which are binaries must contain the suffix '-bin' to reflect
+this fact. Similarly, packages which pull from git should contain the
+suffix '-git'. The version of git packages must 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 should 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: cp "file" "$1/usr/bin/file"
+ Good: cp file "$1/usr/bin/file"
+
+
+%[0209]
+
+Quote entire strings instead of variables.
+
+ Bad: cp -f cat "$1"/usr/bin/cat
+ Good: cp -f cat "$1/usr/bin/cat"
+
+
+%[0210]
+
+Align arguments in blocks of command calls.
+
+Bad:
+
+ cp file.h "$1/usr/include/file.h"
+ cp libfile.so "$1/usr/lib/libfile.so"
+
+Good:
+
+ cp file.h "$1/usr/include/file.h"
+ cp libfile.so "$1/usr/lib/libfile.so"
+
+
+%[0211]
+
+Use `mkdir` and `cp` instead of `install`.
+
+Bad:
+
+ install -Dm755 ls "$1/usr/bin/ls"
+
+Good:
+
+ mkdir -p "$1/usr/bin"
+ cp ls "$1/usr/bin/"
+
+NOTE: since Dylan wrote this style guide, he changed opinions on this point
+since install isn't POSIX. Both styles are accepted in the community repo.
+
+
+%[0212]
+
+Prefer `$CC` to ...
+
+ Bad: gcc -o file file.c
+ Good: "${CC:-cc}" -o file file.c
+
+
+%[0213]
+
+Always use `-p` with `mkdir`.
+
+
+%[0214]
+
+Always use `printf`. Do not use `echo`.
+
+
+
+### 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 preferred 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]
+
+If dependency is unneeded, then it must be removed.
+
+
+%[1202]
+
+Some packages are assumed to always be available. Such dependency must be
+removed.
+
+Examples: gcc, make, musl.
+
+
+%[1203]
+
+Build-time dependencies must be marked as 'make' dependencies.
+
+Examples: autoconf, automake, cmake, meson.
+
+
+%[1204]
+
+Runtime dependencies must not be marked as 'make' dependencies.
+
+
+%[1205]
+
+The depends file must be sorted.
+
+
+%[1206]
+
+If depends file is empty, then it must 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]
+
+Package version must be latest upstream version.
+
+
+%[1602]
+
+Use 'git' in place of '9999'.
+
+
+%[1603]
+
+The version file must contain 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.
