Feat: convert docs from Ikiwiki to MkDocs

13 files changed, 689 insertions, 0 deletions

diff --git a/docs/basics.md b/docs/basics.md
new file mode 100644
index 0000000..6eafa91
--- /dev/null
+++ b/docs/basics.md
@@ -0,0 +1,74 @@
+# Basic packaging
+
+## Configuration files
+
+All the commands in this guide assumes that you're using [these configuration
+files](https://git.fluxo.info/?p=rhatto/dotfiles/debian.git;a=summary).
+
+## Starting a new package
+
+We use the `packages/` folder from this repo to store sources:
+
+    mkdir packages/$package
+    cd packages/$package
+
+## Getting the debianized source
+
+Using `dget`:
+
+    dget $remote_dsc
+    cd $package*
+
+Using `apt-get`:
+
+    apt-get source package
+
+## Checking the source
+
+See `checking.md`.
+
+## Extracting the source
+
+If needed, do this after your successfully verified the sources:
+
+    dpkg-source -x *.dsc
+
+## Getting dependencies
+
+To get:
+
+    apt-get build-dep package
+
+To remove:
+
+    hydractl remove-dep package
+
+## Creating the `debian/` structure
+
+If the package wasn't debianized, proceed with
+
+    if [ ! -d "debian" ]; then
+      dh_make -p ${package}_${version} --createorig
+    fi
+
+## Simple build
+
+    dch -i
+    dpkg-buildpackage -rfakeroot -sa -k$KEY_ID
+
+## Creating a new debian source
+
+    cd ..
+    dpkg-source -b $package*
+    debsign $package*.dsc
+
+## Building and signing
+
+To generate signatures, remove `-uc` and `-us` from `dpkg-buildpackage` (see
+[Complete build](http://www.debian.org/doc/maint-guide/ch-build.pt-br.html#s-completebuild)):
+
+    dpkg-buildpackage -rfakeroot
+
+To sign using an specific key:
+
+    dpkg-buildpackage -rfakeroot -kKEY_ID
diff --git a/docs/building.md b/docs/building.md
new file mode 100644
index 0000000..0f7009c
--- /dev/null
+++ b/docs/building.md
@@ -0,0 +1,36 @@
+# Building
+
+## Standard build
+
+    DIST=stretch sudo -E cowbuilder --build $package*.dsc
+
+## Signing
+
+To sign both the `.dsc` and the `.changes` files:
+
+    debsign $package*.changes
+
+## Uploading
+
+Simply run
+
+    dupload *changes
+
+This assumes a `~/.dupload.conf` like the following:
+
+    package config;
+    $default_host = "myremote";
+
+    $cfg{'myremote'} = {
+            fqdn     => "myremote.example.org",
+            login    => "user",
+            method   => "scpb",
+            incoming => "/var/reprepro/incoming/",
+            # The dinstall on ftp-master sends emails itself
+            #dinstall_runs => 1,
+    };
+
+It's also important that:
+
+  1. The host remote port is correctly defined at your `~/.ssh/config`.
+  2. The user is in the `reprepro` group in the server.
diff --git a/docs/checking.md b/docs/checking.md
new file mode 100644
index 0000000..ee3f32c
--- /dev/null
+++ b/docs/checking.md
@@ -0,0 +1,124 @@
+# Integrity checking
+
+## Debian Images
+
+See [Verifying authenticity of Debian CDs](https://www.debian.org/CD/verify).
+
+## Source packages
+
+This is the trick part. In theory, you could run just
+
+    dscverify *.dsc
+
+Which would check if the signature was made for a key included in the `debian-keyring` package or if you
+have a verification path with the signing key.
+
+In practice, it should always work for sources you download from the **same** Debian version you're running.
+But sources you download from newer versions might not work, depending basically if the maintainer's key is
+already on the `debian-keyring` you installed.
+
+### Using a newer debian-keyring package
+
+You might want to try a newer `debian-keyring` package (for testing or unstable), which we haven't tested
+yet but can reduce a lot of complexity that follows.
+
+### Install manually debian-keyring somewhere
+
+If not, you might try to have a newer copy of the `debian-keyring` somewhere. We already provide one in the
+a way for you to get the keyring directly from https://keyring.debian.org:
+
+    make keyring
+
+We use `--no-default-keyring` to make sure `gpg` just looks for the key in the `debian-maintainers` keyring:
+
+    gpg --no-default-keyring --keyring /path/to/debian/keyring/keyrings/debian-keyring.gpg --verify *.dsc
+
+You might also want to have the following on your `~/.devscripts` (line break just to keep formatting here):
+
+    DSCVERIFY_KEYRINGS="/usr/share/keyrings/debian-keyring.gpg:/usr/share/keyrings/debian-maintainers.gpg:
+                        /path/to/debian/keyring/keyrings/debian-keyring.gpg:/path/to/debian/keyring/keyrings/debian-maintainers.gpg"
+
+Or you can use the following alias:
+
+    alias dscverify='dscverify --keyring /path/to/debian/keyring/keyrings/debian-keyring.gpg --keyring /path/to/debian/keyring/keyrings/debian-maintainers.gpg'
+
+### Manually getting the key
+
+Another option is to get the specific key:
+
+    gpg --recv-keys 12345678
+
+Either way, you have to have a criteria about how much trust you should give to the keyring or the pubkey
+you just downloaded. The same goes for software you're porting to Debian and that you can't actually check
+it's signature against `debian-keyring`.
+
+### Issues with dpkg-source
+
+Things get even trickier when you try to use `dpkg-source`. See [Debian Bug report logs - #852019 gpgv: unknown
+type of key resource 'trustedkeys.kbx'](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=852019)
+for details.
+
+Even if you merge both `keyring/keyrings/debian-keyring.gpg` `keyring/keyrings/debian-maintainers.gpg`
+into some file like `keyring/keyrings/pubring.kbx`, symlink it as `keyring/keyrings/trustedkeys.gpg`
+and point `GNUPGHOME` to this folder you'll still get a weird behavior:
+
+    0 $ dget http://ftp.de.debian.org/debian/pool/main/r/ruby-childprocess/ruby-childprocess_0.5.2-1.dsc
+    dget: retrieving http://ftp.de.debian.org/debian/pool/main/r/ruby-childprocess/ruby-childprocess_0.5.2-1.dsc
+      % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                     Dload  Upload   Total   Spent    Left  Speed
+    100  1827  100  1827    0     0   2626      0 --:--:-- --:--:-- --:--:--  4911
+    dget: retrieving http://ftp.de.debian.org/debian/pool/main/r/ruby-childprocess/ruby-childprocess_0.5.2.orig.tar.gz
+      % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                     Dload  Upload   Total   Spent    Left  Speed
+    100 26055  100 26055    0     0  20738      0  0:00:01  0:00:01 --:--:-- 27455
+    dget: retrieving http://ftp.de.debian.org/debian/pool/main/r/ruby-childprocess/ruby-childprocess_0.5.2-1.debian.tar.xz
+      % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                     Dload  Upload   Total   Spent    Left  Speed
+    100  2892  100  2892    0     0   4183      0 --:--:-- --:--:-- --:--:--  8078
+    ruby-childprocess_0.5.2-1.dsc:
+          Good signature found
+       validating ruby-childprocess_0.5.2.orig.tar.gz
+       validating ruby-childprocess_0.5.2-1.debian.tar.xz
+    All files validated successfully.
+    gpgv: Signature made Seg 28 Abr 2014 18:03:27 BRT using RSA key ID 39CD217A
+    gpgv: Impossível verificar assinatura: chave pública não encontrada
+    dpkg-source: warning: failed to verify signature on ./ruby-childprocess_0.5.2-1.dsc
+    dpkg-source: info: extracting ruby-childprocess in ruby-childprocess-0.5.2
+    dpkg-source: info: unpacking ruby-childprocess_0.5.2.orig.tar.gz
+    dpkg-source: info: unpacking ruby-childprocess_0.5.2-1.debian.tar.xz
+    0 $
+
+What happened here is that `dscverify` honoured our custom configuration above while `dpkg-source` is still relying on
+the one available in the `debian-keyring` package.
+
+Even if you remove the `debian-keyring` package, it will still fallback to your `$HOME/.gnupg/trustedkeys.gpg` which
+you don't really want to fill with keys you actually haven't stablished a proper trust relationship.
+
+As currently `dpkg-source` doesn't honour `GNUPGHOME` (see TODO for bugreport), all we can do currently is call `dget`
+and `dpkg-source` with
+
+    HOME=/path/to/debian/keyring/ dpkg-source -x $package*dsc
+    HOME=/path/to/debian/keyring/ dget <remote-dsc>
+
+For this trick to work, you'll need to run
+
+    make keyring
+
+Again, you might set two handy aliases for your shell:
+
+    alias dpkg-source='HOME=/path/to/debian/keyring/keyrings/ dpkg-source'
+    alias dget='HOME=/path/to/debian/keyring/keyrings/ dget'
+
+Optionally, as a last touch, import your own key into this keyring:
+
+    gpg --armor --export $KEYID | \
+    gpg --no-default-keyring --keyring /path/to/debian/keyring/keyrings/.gnupg/trustedkeys.gpg --import
+
+Then you might be happy... for a while :P
+
+See also:
+
+* `dscverify(1)` manpage.
+* [Debian Public Key Server](http://keyring.debian.org/) and it's [workflow](https://keyring.debian.org/keyring-workflow.html).
+* [apt get - How to get apt-get source verification working? - Super User](https://superuser.com/questions/626810/how-to-get-apt-get-source-verification-working).
+* [Debian. How can I securely get debian-archive-keyring, so that I can do an apt-get update? NO_PUBKEY - Server Fault](http://serverfault.com/questions/337278/debian-how-can-i-securely-get-debian-archive-keyring-so-that-i-can-do-an-apt-g/337283#337283).
diff --git a/docs/cross.md b/docs/cross.md
new file mode 100644
index 0000000..45255f7
--- /dev/null
+++ b/docs/cross.md
@@ -0,0 +1,73 @@
+# Crosscompilation
+
+## Basic references
+
+* [BuildingCrossCompilers - Debian Wiki](http://wiki.debian.org/BuildingCrossCompilers).
+* [EmdebianToolchain - Debian Wiki](http://wiki.debian.org/EmdebianToolchain).
+* [EmDebian/CrossDebootstrap - Debian Wiki](http://wiki.debian.org/EmDebian/CrossDebootstrap).
+* [QemuUserEmulation - Debian Wiki](http://wiki.debian.org/QemuUserEmulation).
+* [software development - How do I build a GCC 4.7 toolchain for cross-compiling? - Raspberry Pi Stack Exchange](http://raspberrypi.stackexchange.com/questions/1/how-do-i-build-a-gcc-4-7-toolchain-for-cross-compiling).
+* [ARM cross-compiling howto - K's cluttered loft](http://www.ailis.de/~k/archives/19-arm-cross-compiling-howto.html).
+* [Debian ARM Cross-compile - Manuals](http://wiki.micromint.com/index.php/Debian_ARM_Cross-compile).
+* [How to cross-compile Git for ARM?](http://stackoverflow.com/questions/15516168/how-to-cross-compile-git-for-arm).
+* [Allow to compile with Debian/Ubuntu ARM toolchain · Issue #34 · libopencm3/libopencm3](https://github.com/libopencm3/libopencm3/issues/34).
+
+## Basic configuration
+
+    (0) [20130426 13:37:57] vagrant@vagrant-debian-wheezy:~ $ cat /etc/apt/sources.list.d/emdebian.list
+    #
+    # -- Emdebian cross toolchains
+    #
+    # deb http://www.emdebian.org/debian/ unstable main
+    # deb http://www.emdebian.org/debian/ testing main
+    deb http://www.emdebian.org/debian wheezy main
+    (0) [20130426 13:38:12] vagrant@vagrant-debian-wheezy:~ $
+
+    (0) [20130426 13:38:12] vagrant@vagrant-debian-wheezy:~ $ cat /etc/apt/sources.list.d/squeeze.list 
+    deb http://http.debian.net/debian/ squeeze main contrib non-free
+    deb-src http://http.debian.net/debian/ squeeze main contrib non-free
+    (0) [20130426 13:38:44] vagrant@vagrant-debian-wheezy:~ $ 
+
+## Exemplo: git
+
+Instalando as dependências do git:
+
+    xapt -a armel -m  asciidoc comerr-dev cvs cvsps docbook-xml docbook-xsl krb5-multidev libapr1 libaprutil1 libcurl4-gnutls-dev libdbd-sqlite3-perl libdbi-perl libexpat1-dev libgcrypt11-dev libgnutls-dev libgnutls-openssl27 libgnutlsxx27 libgpg-error-dev libidn11-dev libkadm5clnt-mit8 libkadm5srv-mit8 libkdb5-6 libkrb5-dev libldap2-dev libneon27-gnutls libnet-daemon-perl libp11-kit-dev libplrpc-perl librtmp-dev libssh2-1-dev libsvn-perl libsvn1 libtasn1-3-dev libxml2-utils libxslt1.1 libyaml-perl pkg-config sgml-data subversion xmlto xsltproc zlib1g-dev libssl-dev
+
+Tentando compilar com a [seguinte instrução](https://www.olimex.com/forum/index.php?topic=496.0):
+
+    ./configure --build=arm --host=arm-linux-gnueabi
+    make ARCH=arm CROSS_COMPILE=arm-linux-gnueabi install prefix=$(pwd)/../destdir/
+
+## Criando um toolchain
+
+Primeiro, como `root`, vamos criar o chroot:
+
+    mkdir -p /var/chroot
+    debootstrap --verbose --arch armel --foreign wheezy /var/chroot/wheezy-armel http://ftp.debian.org/debian
+    cp /usr/bin/qemu-arm-static /var/chroot/wheezy-armel/usr/bin/
+    DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true \
+     LC_ALL=C LANGUAGE=C LANG=C chroot /var/chroot/wheezy-armel /debootstrap/debootstrap --second-stage
+
+Opcionalmente, dê permissão ao usuário comum:
+
+    chown -R vagrant. /var/chroot/wheezy-armel
+
+Como usuário comum:
+
+    cd /var/chroot/wheezy-armel
+    sb2-init -n -m emulate -c /usr/bin/qemu-arm wheezy-armel "arm-linux-gnueabi-gcc"
+
+## Referências
+
+Script [provision-chroot](https://git.fluxo.info/hydra/tree/share/hydractl/provision-chroot).
+* [Set up sb2 with armel debootstrap - maemo.org - Talk](http://talk.maemo.org/showthread.php?t=83713).
+* [Installing scratchbox 1 and 2 for ARM cross-compilation | Felipe Contreras](https://felipec.wordpress.com/2009/06/07/installing-scratchbox-1-and-2-for-arm-cross-compilation/).
+* [MobileRead Wiki - Boox M92 Development with Scratchbox2](http://wiki.mobileread.com/wiki/Boox_M92_Development_with_Scratchbox2).
+* [Cross Compile environment using debootstrap and scratchbox2 | Rogerio Moraes](http://rogeriomoraes.com/wp/?p=41).
+* [Using scratchbox2 and Ubuntu 11.10 | Hamilton Vera](https://hvera.wordpress.com/2011/12/07/using-scratchbox2/).
+* [Setting up Scratchbox2 to build software for zubuntu « Executing Gummiworms](http://russelldavis.org/2010/10/20/setting-up-scratchbox2-to-build-software-for-zubuntu/).
+
+## Problemas encontrados
+
+* [debootstrap --second-stage fails because of /dev/ mapping](http://comments.gmane.org/gmane.comp.compilers.scratchbox.user/1420).
diff --git a/docs/custom/leap.md b/docs/custom/leap.md
new file mode 100644
index 0000000..cd657c9
--- /dev/null
+++ b/docs/custom/leap.md
@@ -0,0 +1,147 @@
+# Example: packaging leap_cli and dependencies
+
+Upstream: https://leap.se/code/issues/6503
+
+## Determine dependencies
+
+First, in a *fresh* vagrant box with *sid* and *testing* in the `sources.list`:
+
+    sudo apt-get install rubygems gem2deb
+    sudo gem install leap_cli
+
+Then we get the dependencies and build all packages:
+
+    dependencies=" `gem list | cut -d '(' -f 1` "
+
+Which currently gives us the following result:
+
+* activemodel
+* activesupport
+* base32
+* blockenspiel
+* builder
+* capistrano
+* colored
+* command_line_reporter
+* gli
+* gpgme
+* highline
+* i18n
+* json
+* json_pure
+* leap_cli
+* mini_portile
+* minitest
+* net-scp
+* net-sftp
+* net-ssh
+* net-ssh-gateway
+* paint
+* tee
+* thread_safe
+* tzinfo
+* versionomy
+* ya2yaml
+
+Gem cleanup:
+
+    sudo gem uninstall $dependencies
+
+Check existing dependencies:
+
+    for item in $dependencies; do
+      package=ruby-"`echo $item | sed -e 's/_/-/'`"
+      packages="$packages $package"
+    done
+
+    apt-get install --dry-run $packages
+
+Then:
+
+* Check for non-existing packages.
+* Try different package names.
+* Update your list of existing `$packages`.
+
+In this example we have the following `$already_ported` dependencies:
+
+* capistrano
+* ruby-activemodel
+* ruby-activesupport
+* ruby-blockenspiel
+* ruby-builder
+* ruby-colored
+* ruby-gpgme
+* ruby-highline
+* ruby-i18n
+* ruby-json
+* ruby-minitest
+* ruby-net-scp
+* ruby-net-sftp
+* ruby-net-ssh
+* ruby-net-ssh-gateway
+* ruby-paint
+* ruby-thread-safe
+* ruby-tzinfo
+* ruby-versionomy
+
+That means the following `$gems` needs to be packaged:
+
+* base32
+* command_line_reporter
+* gli
+* json_pure (we can just use ruby-json and ignore this dependency)
+* leap_cli
+* mini_portile
+* tee
+* ya2yaml
+
+In summary, we need to port the following `$new_packages`:
+
+* ruby-base32
+* ruby-command-line-reporter
+* ruby-gli
+* ruby-mini-portile
+* ruby-tee
+* ruby-ya2yaml
+* ruby-leap-cli
+
+## Build remaining packages
+
+    for gem in $gems; do
+      gem2deb $gem
+    done
+
+## Getting the source for the existing packages
+
+    for package in $already_ported; do
+      apt-get -t jessie source --download-only $package
+      dpkg-source -x $package*dsc
+    done
+
+## Next steps
+
+* Fix `debian/control` and other `FIXME` on each package.
+* Put `debian/` folder in a `debian` branch on each source.
+* Fix [tests](https://wiki.debian.org/Teams/Ruby/Packaging/Tests).
+* [Other best practices](https://wiki.debian.org/Teams/Ruby/RubyExtras/UpstreamDevelopers).
+* [Review the code](https://manual.sarava.org/specs/code/).
+* Automate building with pbuilder for `sid`.
+* Fix lintian warnings.
+* Upstream pull requests.
+* Backport everything to `wheezy`.
+
+## Per-package tasks
+
+* ruby-faker:
+  * https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=765124
+  * https://github.com/rails/rails/issues/13164
+* ruby-leap-cli:
+  * net-ssh compatibility:
+    * https://github.com/net-ssh/net-ssh/issues/145
+    * https://github.com/capistrano/capistrano/issues/927
+  * workflow:
+
+    git checkout develop
+    git archive --prefix=leap-cli-1.5.6/ --format=tar HEAD | bzip2 > ../tarballs/leap-cli-1.5.6.tar.bz2
+    git checkout debian
+    git-buildpackage --git-ignore-branch
diff --git a/docs/custom/python.md b/docs/custom/python.md
new file mode 100644
index 0000000..85dd263
--- /dev/null
+++ b/docs/custom/python.md
@@ -0,0 +1,52 @@
+# Python packaging
+
+## Old procedure
+
+Example: using [stdeb](http://github.com/astraw/stdeb) to build [http://kedpm.sf.net].
+
+    sudo apt-get install stdeb fakeroot
+    sudo apt-get install python-crypto libglade2-0 python-gtk2 python-glade2
+
+File `~/.pydistutils.cfg`:
+
+    [sdist_dsc]
+    force-buildsystem: False
+
+File `kedpm.cfg`:
+
+    [DEFAULT]
+    Package: kedpm
+    Maintainer: User Name <user@example.org>
+    Depends: python-crypto
+
+Getting the code:
+
+    wget http://downloads.sourceforge.net/project/kedpm/kedpm/0.4.0/kedpm-0.4.0.tar.gz
+
+Packaging:
+
+    py2dsc --extra-cfg-file kedpm.cfg kedpm-0.4.0.tar.gz
+    cd deb_dist/kedpm-0.4.0
+    dpkg-buildpackage -rfakeroot -uc -us
+    cd ..
+    sudo dpkg -i kedpm_0.4.0-1_all.deb
+
+## References
+
+* [Python/Pybuild - Debian Wiki](https://wiki.debian.org/Python/Pybuild "Python/Pybuild - Debian Wiki")
+  * [Packaging Python Applications for Debian | Snakes on Callisto](https://jhermann.github.io/blog/python/devops/2020/03/28/dh_virtualenv_howto.html "Packaging Python Applications for Debian | Snakes on Callisto")
+  * [Debian -- Details of package python3-stdeb in bullseye](https://packages.debian.org/bullseye/python3-stdeb "Debian -- Details of package python3-stdeb in bullseye")
+  * [Creating configuration files in /etc in Debian packages - pi3g.com](https://pi3g.com/2020/04/05/creating-configuration-files-in-etc-in-debian-packages/ "Creating configuration files in /etc in Debian packages - pi3g.com")
+  * [PbuilderHowto - Ubuntu Wiki](https://wiki.ubuntu.com/PbuilderHowto "PbuilderHowto - Ubuntu Wiki")
+  * [PyBuilder — Tutorial](https://pybuilder.io/documentation/tutorial "PyBuilder — Tutorial")
+    * [Distributing Python Modules (Legacy version) — Python 3.10.4 documentation](https://docs.python.org/3/distutils/index.html "Distributing Python Modules (Legacy version) — Python 3.10.4 documentation")
+      * [Distributing Python Modules — Python 3.10.4 documentation](https://docs.python.org/3/distributing/index.html#distributing-index "Distributing Python Modules — Python 3.10.4 documentation")
+      * [What’s New In Python 3.10 — Python 3.10.4 documentation](https://docs.python.org/3/whatsnew/3.10.html#distutils-deprecated "What’s New In Python 3.10 — Python 3.10.4 documentation")
+        * [PEP 632 – Deprecate distutils module | peps.python.org](https://peps.python.org/pep-0632/ "PEP 632 – Deprecate distutils module | peps.python.org")
+    * [python - setup.py build doesn't work but develop does - Stack Overflow](https://stackoverflow.com/questions/38729475/setup-py-build-doesnt-work-but-develop-does "python - setup.py build doesn't work but develop does - Stack Overflow")
+    * [pybuild(1) — dh-python — Debian testing — Debian Manpages](https://manpages.debian.org/testing/dh-python/pybuild.1.en.html "pybuild(1) — dh-python — Debian testing — Debian Manpages")
+  * [Debian -- Details of package dh-python in bullseye-backports](https://packages.debian.org/bullseye-backports/dh-python "Debian -- Details of package dh-python in bullseye-backports")
+    * [#1001459 - dh-python: SetuptoolsDeprecationWarning: setup.py install is deprecated - Debian Bug report logs](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1001459 "#1001459 - dh-python: SetuptoolsDeprecationWarning: setup.py install is deprecated - Debian Bug report logs")
+    * [Bugs in package dh-python (version 5.20220403) in unstable -- Debian Bug report logs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?pkg=dh-python;dist=unstable "Bugs in package dh-python (version 5.20220403) in unstable -- Debian Bug report logs")
+  * [Debian Python Policy — Debian Python Documentation Project 1.0 documentation](https://debian-python.readthedocs.io/en/latest/debian-policy.html "Debian Python Policy — Debian Python Documentation Project 1.0 documentation")
+    * [dh-python/plugin_distutils.py at master · p1otr/dh-python](https://github.com/p1otr/dh-python/blob/master/dhpython/build/plugin_distutils.py "dh-python/plugin_distutils.py at master · p1otr/dh-python")
diff --git a/docs/custom/ruby.md b/docs/custom/ruby.md
new file mode 100644
index 0000000..be79085
--- /dev/null
+++ b/docs/custom/ruby.md
@@ -0,0 +1,4 @@
+# Ruby packaging
+
+* See [this](https://wiki.debian.org/Teams/Ruby/Packaging).
+* Example: [LEAP](/leap).
diff --git a/docs/env.md b/docs/env.md
new file mode 100644
index 0000000..cb38509
--- /dev/null
+++ b/docs/env.md
@@ -0,0 +1,54 @@
+# Environment
+
+## Build environment creation
+
+The following steps needs to be run just once for each arch and distro version.
+
+### Setup cowbuilder chroots
+
+This is the recommended method:
+
+    sudo mkdir -p /var/cache/pbuilder/sid-amd64
+    sudo -E cowbuilder --create
+
+    sudo mkdir -p /var/cache/pbuilder/stretch-amd64
+    sudo -E DIST=stretch cowbuilder --create
+
+### Setup pbuilder chroots
+
+If you want to setup directly using `pbuilder`:
+
+    git-pbuilder create
+    DIST=jessie git-pbuilder
+
+### Compatibility with git-buildpackage
+
+This is a workaround while we don't find a cleaner way to fix
+[this issue](http://ramblingfoo.blogspot.com.br/2012/10/howto-sudo-cowbuilder-git-buildpackage.html)
+with `git-buildpackage` not getting `~/.pbuilderrc` from the local user:
+
+    ( cd /var/cache/pbuilder/ && sudo ln -s sid-amd64/base.cow )
+
+## External repository integration
+
+If your package storage lives elsewhere, make a symlink like this:
+
+    (
+      cd /var/cache/pbuilder/jessie-amd64 && \
+      sudo rm -rf result                  && \
+      sudo ln -s /var/data/distros/debian/packages/build-area/jessie-amd64 result
+    )
+
+## Environment maintenance
+
+These steps should be run once in a while to ensure we have an up to date packaging environment.
+
+### Pbuilder
+
+    DIST=sid    git-pbuilder update
+    DIST=jessie git-pbuilder update --override-config
+
+### Cowbuilder
+
+    DIST=sid    sudo -E cowbuilder --update
+    DIST=jessie sudo -E cowbuilder --update --override-config
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..6e416b6
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,12 @@
+# Debian packaging effort!
+
+In the past, we used to be [heavy slackware
+users](https://simplepkg.fluxo.info) when we just had a few boxes to manage.
+Then we had to change our whole packaging paradigm when we switched to Debian.
+
+These notes are mainly references to the detailed Debian/Ubuntu documentations
+we're using in the course of learning the intricacies of Debian packaging.
+
+Grab this repository using
+
+    git clone --recursive https://git.fluxo.info/debian
diff --git a/docs/itp.md b/docs/itp.md
new file mode 100644
index 0000000..a0692ee
--- /dev/null
+++ b/docs/itp.md
@@ -0,0 +1,13 @@
+# ITP
+
+## WNPP
+
+Before packaging anything, have a look at:
+
+* [WNPP](http://wnpp.debian.net).
+* [Debian Git](http://anonscm.debian.org/gitweb/).
+
+## Software
+
+* [zathura-epub](https://git.pwmt.org/pwmt/zathura-epub).
+* [bdsync](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=724344).
diff --git a/docs/references.md b/docs/references.md
new file mode 100644
index 0000000..0080468
--- /dev/null
+++ b/docs/references.md
@@ -0,0 +1,66 @@
+# References
+
+## General
+
+* [Debian New Maintainers' Guide](https://www.debian.org/doc/manuals/maint-guide/).
+* [Debian Developer's Reference](https://www.debian.org/doc/manuals/developers-reference/)
+* [Debian Policy Manual](https://www.debian.org/doc/debian-policy/).
+* [Guide for Debian Maintainers](https://www.debian.org/doc/manuals/debmake-doc/index.en.html)
+* [Overview — Ubuntu Packaging Guide](http://packaging.ubuntu.com/html/).
+* [Debugging Debian package installations](http://mdcc.cx/debian/debugging_debian_package_installations.html).
+* [Quick Debian development guide - anarcat](https://anarc.at/software/debian-development/ "Quick Debian development guide - anarcat")
+
+## Pbuilder and cowbuilder
+
+* [PbuilderTricks](https://wiki.debian.org/PbuilderTricks).
+* [cowbuilder](https://wiki.debian.org/cowbuilder).
+
+## Sbuild
+
+* [sbuild - Debian Wiki](https://wiki.debian.org/sbuild#Delete_a_chroot "sbuild - Debian Wiki")
+  * [sbuild-debian-developer-setup(1) — sbuild — Debian unstable — Debian Manpages](https://manpages.debian.org/unstable/sbuild/sbuild-debian-developer-setup.1 "sbuild-debian-developer-setup(1) — sbuild — Debian unstable — Debian Manpages")
+
+## Backporting
+
+* [Backporting Debian packages with pbuilder](http://www.tolaris.com/2009/03/31/backporting-debian-packages-with-pbuilder/).
+* [Using pbuilder to backport Debian packages](http://edseek.com/~jasonb/articles/pbuilder_backports/).
+* [BuildingFormalBackports - Debian Wiki](https://wiki.debian.org/BuildingFormalBackports#Building_multi-dependencies_packages).
+
+## Packaging with git
+
+* [Co-maintaining a Debian package with Git and git-buildpackage | workaround.org](https://workaround.org/debian-git-comaintenance).
+* [PackagingWithGit - Debian Wiki](https://wiki.debian.org/PackagingWithGit).
+* [Building Debian Packages with git-buildpackage](http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.html).
+
+## Linting
+
+* [Lintian Tag](https://lintian.debian.org/tags "Lintian Tag") list.
+
+## Piuparts
+
+* [piuparts - Debian Wiki](https://wiki.debian.org/piuparts)
+* [piuparts.debian.org/doc/README.txt](https://piuparts.debian.org/doc/README.txt)
+
+## Security and Hardening
+
+* [Hardening - Debian Wiki](https://wiki.debian.org/Hardening)
+* [ServiceSandboxing - Debian Wiki](https://wiki.debian.org/ServiceSandboxing)
+
+## Account handling
+
+* [AccountHandlingInMaintainerScripts - Debian Wiki](https://wiki.debian.org/AccountHandlingInMaintainerScripts "AccountHandlingInMaintainerScripts - Debian Wiki")
+  * [How Debian package should create user accounts? - Unix & Linux Stack Exchange](https://unix.stackexchange.com/questions/47880/how-debian-package-should-create-user-accounts "How Debian package should create user accounts? - Unix & Linux Stack Exchange")
+
+## Systemd
+
+* [Teams/pkg-systemd/Packaging - Debian Wiki](https://wiki.debian.org/Teams/pkg-systemd/Packaging "Teams/pkg-systemd/Packaging - Debian Wiki")
+  * [How can I Debian-package a python application with a systemd unit using stdeb3/py2dsc and dpkg-buildpackage? - Stack Overflow](https://stackoverflow.com/questions/64345965/how-can-i-debian-package-a-python-application-with-a-systemd-unit-using-stdeb3-p "How can I Debian-package a python application with a systemd unit using stdeb3/py2dsc and dpkg-buildpackage? - Stack Overflow")
+  * [packaging - How to package a systemd service? - Ask Ubuntu](https://askubuntu.com/questions/746094/how-to-package-a-systemd-service "packaging - How to package a systemd service? - Ask Ubuntu")
+  * [configuration - How do I override or configure systemd services? - Ask Ubuntu](https://askubuntu.com/questions/659267/how-do-i-override-or-configure-systemd-services#659268 "configuration - How do I override or configure systemd services? - Ask Ubuntu")
+
+## SysUser
+
+* [Teams/Dpkg/Spec/SysUser - Debian Wiki](https://wiki.debian.org/Teams/Dpkg/Spec/SysUser)
+* [dh_sysuser(1) — dh-sysuser — Debian testing — Debian Manpages](https://manpages.debian.org/testing/dh-sysuser/dh_sysuser.1.en.html)
+* [Debian / dh-sysuser · GitLab](https://salsa.debian.org/debian/dh-sysuser)
+* [dh-sysuser. Yesterday I’ve discovered a dh-sysuser… | by George Shuklin | OpsOps | Medium](https://medium.com/opsops/dh-sysuser-6bd3e3d623dd)
diff --git a/docs/repositories.md b/docs/repositories.md
new file mode 100644
index 0000000..d6cf48e
--- /dev/null
+++ b/docs/repositories.md
@@ -0,0 +1,27 @@
+# Repositories
+
+## Documentation
+
+* [DebianRepository/Setup - Debian Wiki](https://wiki.debian.org/DebianRepository/Setup).
+* [Debian Repository HOWTO (Obsolete Documentation)](https://www.debian.org/doc/manuals/repository-howto/repository-howto).
+* [HowToSetupADebianRepository](https://wiki.debian.org/HowToSetupADebianRepository).
+* [Setting up your own APT repository with upload support](http://www.debian-administration.org/article/286/Setting_up_your_own_APT_repository_with_upload_support).
+
+## Reprepro
+
+* [puppet-reprepro](https://git.fluxo.info/puppet-reprepro).
+Alguns links sobre como instalar e usar o reprepro:
+* [reprepro](http://mirrorer.alioth.debian.org/).
+* [HowToSetupADebianRepository](http://wiki.debian.org/HowToSetupADebianRepository).
+* [Setting up your own APT repository with upload support](http://www.debian-administration.org/article/Setting_up_your_own_APT_repository_with_upload_support).
+* [Setting up a basic Debian repository with reprepro](https://noc.sidux.com/fll/wiki/reprepro).
+* [Setting up and managing an APT repository with reprepro](http://www.jejik.com/articles/2006/09/setting_up_and_managing_an_apt_repository_with_reprepro/).
+
+Removing a package from the repository:
+
+    su reprepro -c "reprepro -b /var/reprepro remove squeeze kedpm"
+
+## Other
+
+* [aptly - Debian repository management tool](https://www.aptly.info/) ([package](https://packages.debian.org/stretch/aptly)).
+* [debify: Tool for building simple Debian repositories](https://github.com/spotify/debify).
diff --git a/docs/todo.md b/docs/todo.md
new file mode 100644
index 0000000..713b4a7
--- /dev/null
+++ b/docs/todo.md
@@ -0,0 +1,7 @@
+# TODO
+
+* Merge all `build-area` folders.
+* Deploy debian project as a ikiwiki with a git-annex'ed package repository.
+* Try an [AutomateBackports](https://wiki.debian.org/AutomateBackports) setup.
+* Set [SecurePbuilder](https://wiki.debian.org/SecurePbuilder).
+* How to make an offline apt-repository in an encrypted usb drive.