docs

Carbs Linux Documentation
git clone git://git.carbslinux.org/docs
Log | Files | Refs | Submodules | README

commit 698d8ebd4c99da1a208c8cbe94d5c12a1c363e39
parent 3a51a65f263f147c53a8ea9c5ef089e6ed482cad
Author: Cem Keylan <cem@ckyln.com>
Date:   Mon, 14 Sep 2020 20:01:49 +0300

update contribution guidelines

Diffstat:
Mcontribution.texi | 275+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 240 insertions(+), 35 deletions(-)

diff --git a/contribution.texi b/contribution.texi @@ -1,74 +1,279 @@ @macro contid{id} -@strong{[@anchor{\id\}\id\]} +[@anchor{\id\}\id\] +@end macro + +@macro sectid{id, sect} +@strong{@contid{\id\} \sect\} @end macro @node Contribution Guidelines @chapter Contribution Guidelines Thanks for taking your time to contribute! To maintain stylistic behaviour -throughout the repositories, one must adhere to these guidelines. Exceptions and -changes may occur with good reasoning. +throughout the repositories, one must adhere to these conventions. Exceptions +and changes may occur with good reasoning. + +@menu +* Conventions:: +* Sending Git mails:: +@end menu @node Conventions @section Conventions -@subsection General Conventions -- 00 -These apply to each and every file on the repositories. +@node General Conventions +@subsection General Conventions -- 00 -@itemize -@item -Try to keep the file readable. @contid{0010} -@itemize -@item -Characters on a line shouldn't exceed 100 characters excluding indentation. @contid{0011} -@item +@table @strong +@item @contid{0010} +Try to keep the file readable. +@table @strong +@item @contid{0011} +Characters on a line shouldn't exceed 100 characters. +@item @contid{0012} Make sure you don't have code commented out during commit. Uncomment them -or remove them completely. @contid{0012} -@item +or remove them completely. +@item @contid{0013} Do not add comments following the code, add them to the top of the code. It -makes it harder to read, and lines longer. @contid{0013} -Here is an example: +makes it harder to read, and lines longer. Here is an example: @example # Good way of commenting. your code goes here your code goes here # Avoid this way of commenting. @end example -@end itemize -@end itemize +@end table +@end table +@node Shell Conventions @subsection Shell Conventions -- 10 Shell is central to Carbs Linux projects. Most of the tools and packages are written in POSIX sh. +@table @strong +@item @contid{1010} +Use 4 spaces for indentation, don't use tabs. +@item @contid{1020} +Make sure you don't use bash-specific code. +@item @contid{1030} +Make sure you lint your code with @command{shellcheck} and if you are new to +POSIX sh, use @command{checkbashisms}. +@item @contid{1040} +Don't spawn new processes if you don't absolutely need to, especially during +string manipulation. +@table @strong +@item @contid{1041} +Never use a program for text manupilation that isn't defined in the POSIX +standard. This includes @command{gawk} and @command{perl}. +@item @contid{1042} +Instead of @code{$(basename $file)}, use @code{$@{file##*@}}. +@item @contid{1043} +Instead of @code{$(dirname $file)}, use @code{$@{file%/*@}}. +@end table +@example +# This is the same thing as @code{basename /path/to/test.asc .asc} + +$ file=/path/to/test.asc file=$@{file##*/@} file=$@{file%.asc@} +$ echo $file +test +@end example +@item @contid{1050} +Instead of backticks, use @verb{|$(..)|}. +@end table + +@node Repository Conventions +@subsection Repository Conventions -- 20 + +Repository conventions are important in order to ensure every package resemble +themselves. Here are the things to keep in mind: + +@table @strong +@item @contid{2010} +Prefer tarballs over git packages unless there is a sensible reason. +Here are some: + @itemize @item -Use 4 spaces for indentation, instead of tabs. @contid{1010} +Every patch is a new release. (See @url{https://github.com/vim/vim, vim}) @item -Make sure you don't use bash-specific code. @contid{1020} +There are no releases. (See @url{https://git.suckless.org/sbase}) @item -Make sure you lint your code with @command{shellcheck} and if you are new to -POSIX sh, use @command{checkbashisms}. @contid{1030} +Following a development branch. @item -Don't spawn new processes if you don't absolutely need to, especially during -string manipulation. @contid{1040} +There has been a long time since the latest release, but upstream is far ahead. +@end itemize + +@item @contid{2020} +Prefer sources without a dependency to @command{automake}. There are usually +distribution tarballs that are @command{autoconf}'ed. Don't submit tarballs +with an automake dependency unless you are @strong{sure} there is no +alternative. +@item @contid{2030} +Avoid these packages: +@table @command +@item dbus +Usually can be disabled by @option{--disable-dbus} +@item gettext +Usually can be disabled by @option{--disable-nls} +@end table +@item @contid{2040} @itemize @item -Never use a program for text manupilation that isn't defined in the POSIX -standard. This includes @command{gawk} and @command{perl}. @contid{1041} +Always install a package to the @file{/usr} prefix. @item -Instead of @code{$(basename $file)}, use @code{$@{file##*@}}. @contid{1042} +All binaries should go to @file{/usr/bin}, not @file{/usr/sbin} or any other +directory. @item -Instead of @code{$(dirname $file)}, use @code{$@{file%/*@}}. @contid{1043} +All libraries should go to @file{/usr/lib}. @end itemize +@item @contid{2050} +All build files on the repository should be a POSIX shell script, and must start +with @code{#!/bin/sh -e}. +@end table + +The next section is about package templates that should be used in order to +ensure stylistic consistency. Note that the option configurations shouldn't be +taken literally, they are meant as examples. + +@sectid{2210, Make} + @example -# This is the same thing as @code{basename /path/to/test.asc .asc} +#!/bin/sh -e -$ file=/path/to/test.asc file=$@{file##*/@} file=$@{file%.asc@} -$ echo $file -test +make +make DESTDIR="$1" PREFIX=/usr install +@end example + +@sectid{2211, Configure/Make} + +@example +#!/bin/sh -e + +./configure \ + --prefix=/usr \ + --disable-option \ + --enable-option + +make +make DESTDIR="$1" install +@end example + + +@sectid{2212, Autoconf/Automake} + +@xref{2020} + +@example +#!/bin/sh -e + +autoreconf -fi + +./configure \ + --prefix=/usr \ + --disable-option \ + --enable-option + +make +make DESTDIR="$1" install +@end example + +@sectid{2220, Meson} + +@example +#!/bin/sh -e + +export DESTDIR=$1 + +meson \ + --prefix=/usr \ + -Doption=false \ + -Doption2=true \ + . output + +ninja -C output +ninja -C output install +@end example + +@sectid{2230, Cmake} + +@example +#!/bin/sh -e + +export DESTDIR=$1 + +cmake -B build \ + -DCMAKE_INSTALL_PREFIX=/usr \ + -DCMAKE_BUILD_TYPE=Release \ + -DOPTION=ON + +cmake --build build +cmake --install build +@end example + +@sectid{2240, Go} + +@example +#!/bin/sh -e + +export GOPATH=$PWD/gopath +trap "go clean -modcache" EXIT INT +go mod vendor + +go build +install -Dm755 program "$1/usr/bin/program" +@end example + +@sectid{2241, Python} + +@example +#!/bin/sh -e + +python setup.py build +python setup.py install --prefix=/usr --root="$1" +@end example + +@node Sending Git mails +@section Sending Git mails + +As mentioned, the preferred way of contribution is via patches. The easiest way +for sending git mails without @command{git send-email} is using @command{msmtp}. +You can install it from the repository by doing: + +@example +$ cpt b msmtp && cpt i msmtp +@end example + +You can then edit @file{~/.config/msmtp/config} to add your email. Here is an +example configuration, you can use @command{pass}, @command{pash}, or any other +password manager that fits your needs: + +@example +defaults +auth on +tls on +tls_trust_file /etc/ssl/certs/ca-certificates.crt +logfile ~/.config/msmtp/msmtp.log +account my-mail +host mail.example.com +port 587 +from me@@example.com +user me@@example.com +passwordeval "pass my-mail" +@end example + +In order to simply send your patch, do the following: + +@example +$ git format-patch --to=~carbslinux/dev+subscribe@@lists.sr.ht -1 --stdout | + msmtp -t -a my-mail +@end example + +You can also send multiple patches by doing the following: + +@example +$ git format-patch --to=~carbslinux/dev+subscribe@@lists.sr.ht <region> + +Edit those files as necessary and send them. +$ for file in *.patch; do msmtp -t -a my-mail < $patch; done @end example -@item -Instead of backticks, use @verb{|$(..)|}. @contid{1050} -@end itemize