Developer guide: fill in chap2 and 3, add Makefile

9 files changed, 478 insertions, 0 deletions

diff --git a/src/devel/1_preparing.xml b/src/devel/1_preparing.xml
new file mode 100644
index 0000000..0966a44
--- /dev/null
+++ b/src/devel/1_preparing.xml
@@ -0,0 +1,260 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter label="1" id="preparing">
+    <title>Preparing Your System</title>
+    <para>Welcome to the Adélie Linux 1.0 Developer's Guide.  This guide will teach you how to develop the software and packages that powers the Adélie Linux distribution.  You may follow along at your own pace.</para>
+    <para>We'll start with installing the software and writing the configuration files necessary to perform development.</para>
+    <section>
+        <title>Installing Development Software</title>
+        <para>In this section, you will learn:</para>
+        <itemizedlist>
+            <listitem><para>How to install software on Adélie Linux;</para></listitem>
+            <listitem><para>What software you will use to develop Adélie Linux; and</para></listitem>
+            <listitem><para>What task each utility in the Adélie Linux development system performs.</para></listitem>
+        </itemizedlist>
+        <para>Please make sure that you are at an Adélie Linux terminal before continuing.</para>
+        <section>
+            <title>Using <command>apk</command> to Install Software</title>
+            <para>The <productname>Alpine Package Keeper</productname> or <command>apk</command> package manager is the central software management tool on the Adélie Linux distribution.
+                For a more thorough introduction to the <command>apk</command> package manager, please consult the Adélie Linux 1.0 Administrator's Guide, chapter 3: "Packages".</para>
+            <para>The <command>apk</command> package manager automatically resolves dependencies for requested software packages, and will automatically remove or "clean up" unneeded dependencies when a software package is removed.
+                If a software package's files become corrupted, it can be reinstalled with the <parameter class="command">fix</parameter> subcommand.</para>
+            <para>The <parameter class="command">add</parameter> subcommand will add the specified package(s) to the system's list of packages, and then resolve all necessary dependent libraries and other software packages to ensure the system has the requested packages installed.
+                The <parameter class="command">del</parameter> subcommand will remove the specified package(s) from the system's list of packages, and then remove any other libraries and software packages that are no longer required for the system's operation.  For example, the command:</para>
+            <para><prompt>#</prompt> <command>apk <parameter>add</parameter> <userinput>build-tools</userinput></command></para>
+            <para>will install the <userinput>build-tools</userinput> package, and any packages and libraries it requires.  Similarly,</para>
+            <para><prompt>#</prompt> <command>apk <parameter>del</parameter> <userinput>libressl-dev</userinput></command></para>
+            <para>will remove the <userinput>libressl-dev</userinput> package, and any packages and libraries that it required and no other package on the system requires.</para>
+        </section>
+        <section>
+            <title>Installing the Adélie Linux Development System</title>
+            <para>The development environment is made of two essential parts: the <package>build-tools</package> package, which provides the basic compiler infrastructure, including a C compiler, build system, linker, assembler, and other utilities; and the <package>abuild</package> package, which takes package "recipe" files with build instructions, and creates the <filename class="extension">APK</filename> package files using them.  You may install these two packages by executing the following command:</para>
+            <para><prompt>#</prompt> <command>apk <parameter>add</parameter> <package>abuild</package> <package>build-tools</package></command></para>
+        </section>
+        <section>
+            <title>Components of the Adélie Linux Development System</title>
+            <para>The development system uses many open-source technologies that work together to provide a responsive, cohesive, libre environment.</para>
+            <variablelist>
+                <title>Development System Components</title>
+                <varlistentry>
+                    <term><package>abuild</package> (<command>abuild</command>)</term>
+                    <listitem><para>Builds <filename class="extension">APK</filename> package files from <filename>APKBUILD</filename> package "recipe" files.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>autoconf</package> (<command>autoconf</command>)</term>
+                    <listitem><para>The <orgname>GNU</orgname> package for generating <filename>./configure</filename> scripts in packages that require them to be generated.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>automake</package> (<command>automake</command>)</term>
+                    <listitem><para>The <orgname>GNU</orgname> package for generating <filename>Makefile</filename>s in packages that use the <package>autoconf</package> package.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>attr</package></term>
+                    <listitem><para>A framework for <firstterm>ACL</firstterm>s or <firstterm>access control list</firstterm>s.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>bash</package> (<command>bash</command>, <command>sh</command>)</term>
+                    <listitem><para>A Unix shell mostly compliant with the <productname>POSIX</productname> standard, used by many packages for build scripts and testing.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>binutils</package> (<command>as</command>, <command>ld</command>, <command>nm</command>, …)</term>
+                    <listitem><para>Low-level development utilities including assembler (<command>as</command>), linker (<command>ld</command>), and others.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>bison</package> (<command>yacc</command>)</term>
+                    <listitem><para>The <orgname>GNU</orgname> version of the <command>yacc</command> compiler generation command.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>bzip2</package> (<command>bzip2</command>, <command>bunzip2</command>, <command>bzless</command>, …)</term>
+                    <listitem><para>A popular compression format, included for the ability to unpack <filename class="extension">.bz2</filename> archives within which packages may be distributed.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>cmake</package> (<command>cmake</command>, <command>ctest</command>)</term>
+                    <listitem><para>The CMake build system, used to build many packages, and the CTest test system, used to prove packages are functioning correctly on the local system.</para></listitem>
+                </varlistentry>
+                 <varlistentry>
+                    <term><package>diffutils</package> (<command>diff</command>, <command>cmp</command>)</term>
+                    <listitem><para>Compares two or more files together, showing the differences.  Used by many test suites, and also useful for troubleshooting and generating <filename class="extension">.patch</filename> files.</para></listitem>
+                </varlistentry>
+               <varlistentry>
+                    <term><package>fakeroot</package></term>
+                    <listitem><para>An environment where a package believes it is running as the root user, but is actually running as the build user.  <!-- Why is this necessary? --></para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>flex</package> (<command>lex</command>)</term>
+                    <listitem><para>The <orgname>GNU</orgname> version of the <command>lex</command> lexer, used for creating parsers in many projects.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>gcc</package> (<command>c99</command>, <command>c11</command>, <command>gcc</command>, <command>g++</command>)</term>
+                    <listitem><para>The <orgname>GNU</orgname> Compiler Collection, a mostly standards-compliant C and C++ compiler.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>git</package> (<command>git</command>)</term>
+                    <listitem><para>A distributed <firstterm>version control system</firstterm> used by many projects to keep a record of file history; the current distribution method for Adélie's package repository.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>gzip</package> (<command>gzip</command>, <command>gunzip</command>)</term>
+                    <listitem><para>A popular, long-standing compression format, included for the ability to unpack <filename class="extension">.gz</filename> archives within which packages may be distributed.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>libarchive</package> (<command>cpio</command>, <command>tar</command>)</term>
+                    <listitem><para><command>tar</command> allows creation of APK files and extraction of a popular archive format; <command>cpio</command> is used to create the initial boot disk for CD images.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>libtool</package> (<command>libtool</command>)</term>
+                    <listitem><para>The <orgname>GNU</orgname> library manipulation tool, used by many packages to create shared (<filename class="extension">.so</filename>) and static (<filename class="extension">.a</filename>) library files.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>lzip</package> (<command>lzip</command>)</term>
+                    <listitem><para>A compression format, included for the ability to unpack <filename class="extension">.lz</filename> archives within which packages may be distributed.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>make</package> (<command>make</command>)</term>
+                    <listitem><para>The <orgname>GNU</orgname> version of the standard Unix <command>make</command> command.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>mawk</package> (<command>awk</command>)</term>
+                    <listitem><para>A <productname>POSIX</productname> compliant implementation of the AWK programming language.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>openssl</package> (<command>openssl</command>)</term>
+                    <listitem><para>A command to sign packages cryptographically, ensuring they are not tampered with when a user downloads them.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>patch</package> (<command>patch</command>)</term>
+                    <listitem><para>The <orgname>GNU</orgname> version of <personname><firstname>Larry</firstname><surname>Wall</surname></personname>'s standard <command>patch</command>utility.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>pax-utils</package> (<command>dumpelf</command>, <command>symtree</command>)</term>
+                    <listitem><para>A collection of utilities to enable the building of packages for the PaX secure operating environment.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>pkgconf</package> (<command>pkgconf</command>, <command>pkg-config</command>)</term>
+                    <listitem><para>A freely licensed, mathematically proven <command>pkg-config</command> implementation, used by package build systems to determine the location of libraries on the system.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>sed</package> (<command>sed</command>)</term>
+                    <listitem><para>The <orgname>GNU</orgname> version of the Unix <command>sed</command> command.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>sudo</package> (<command>sudo</command>)</term>
+                    <listitem><para>Allows a user to run a command as the root user without using the root user's password.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><package>xz</package> (<command>xz</command>, <command>unxz</command>)</term>
+                    <listitem><para>An efficient compression format, included for the ability to unpack <filename class="extension">.xz</filename> archives within which packages may be distributed.</para></listitem>
+                </varlistentry>
+            </variablelist>
+        </section>
+    </section>
+    <section>
+        <title>Packaging Primer</title>
+        <para>In this section, you will learn:</para>
+        <itemizedlist>
+            <listitem><para>How repositories and packages work in the Adélie Linux distribution;</para></listitem>
+            <listitem><para>How to use the <command>abuild</command> command; and</para></listitem>
+            <listitem><para>The options and commands available in <command>abuild</command>.</para></listitem>
+        </itemizedlist>
+        <section>
+            <title>Packages and Repositories</title>
+            <para>The <command>abuild</command> command enables you to build a package file for later installation on to one or more computers running the Adélie Linux dsitribution.  A <firstterm>package file</firstterm> is a kind of archive file that contains two key parts: package metadata, and package content files.</para>
+            <para><firstterm>Package metadata</firstterm> is a collection of information used by a package manager, such as <command>apk</command>, to determine information about the package and the package file, including its name, version, maintainer contact information, installed size on disk, and more.  The <firstterm>package content files</firstterm> are a collection of one or more files that comprise the package itself, including executables, default configuration, data files, and any other files needed for the package to work properly.  In some cases it may also include templates, examples, or documentation.</para>
+            <para>All packages belong to a <firstterm>package repository</firstterm> or <firstterm>repo</firstterm>.  A repository is a collection of related packages.  The Adélie Linux distribution has three main repositories: the <database>system</database> repository, used for system software and important libraries; the <database>user</database> repository, used for the majority of packages that users may be interested in; and the <database>nonfree</database> repository, containing packages that do not have a free or libre license.
+                While you are developing on your own computer, you may have as many, or as few, repositories as you like.  It can use any name except the above three.  You may use a name such as <database>mypackages</database>, or just your username.  The repository is a directory on your computer's hard disk.  You may create it anywhere, but it is highly recommended that you store your repository in your home directory (<filename class="directory">/home/<userinput>yourname</userinput></filename>).</para>
+            <para>Each package you create will have its own directory inside your repository.  If you use the <command>newapkbuild</command> command (discussed later), this will be created for you automatically.  Inside this directory will be at least an <filename>APKBUILD</filename> file, which tells <command>abuild</command> the commands to run to build the package.  It may also contain patches or other files necessary for building the package, if necessary.</para>
+            <para>Typically, the <command>abuild</command> command is executed inside the package's directory (for example, <filename class="directory">/home/<userinput>yourname</userinput>/packages/<userinput>pkgname</userinput></filename>).  However, by setting the <envar>APKBUILD</envar> environment variable to the absolute path on disk to an <filename>APKBUILD</filename> file, you may run <command>abuild</command> from any directory.</para>
+        </section>
+        <section>
+            <title>Using the <command>abuild</command> Command</title>
+            <para>Running the <command>abuild</command> command with no arguments in a directory containing an <filename>APKBUILD</filename> file will cause it to install the dependencies of the package as listed in the <filename>APKBUILD</filename>, and then build the package.  Afterwards, the dependencies of the package that were not already installed on your computer are removed.
+                If the build concluded successfully, the directory tree created for the source code and build system are removed by default.  You may configure what <command>abuild</command> removes when a package concludes building.
+                If the build fails to conclude successfully, no directories are removed by default.  You may configure what <command>abuild</command> removes when a package fails to build.</para>
+            <para><command>abuild</command> has many commands that you may use, for finer-grained control over the build process.  You may use the <command>abuild <parameter class="command">deps</parameter></command> command to only install the dependencies of the package, and use the <command>abuild <parameter class="command">unpack</parameter></command> command to unpack the source archive into the directory tree where it can later be built.  These and many other commands are described in more detail in the following section.</para>
+            <para>There are additionally a number of options that you may pass to <command>abuild</command>, which are also described in more detail in the next section.</para>
+        </section>
+        <section>
+            <title><command>abuild</command> Commands</title>
+            <para><!-- XXX Write this --></para>
+        </section>
+    </section>
+    <section>
+        <title>Configuring Your System</title>
+        <para>In this section, you will learn:</para>
+        <itemizedlist>
+            <listitem><para>How to configure <command>abuild</command> for your environment;</para></listitem>
+            <listitem><para>How to create and use package signing keys; and</para></listitem>
+            <listitem><para>The directory layout used by <command>abuild</command> and how to create it.</para></listitem>
+        </itemizedlist>
+        <para>Please make sure that you are at an Adélie Linux terminal before continuing.</para>
+        <section>
+            <title>Configuring <command>abuild</command> for Your Environment</title>
+            <para>The <command>abuild</command> system reads its configuration from two files on your system, if they exist.
+                The <filename>/etc/abuild.conf</filename> file contains system-wide configuration, used by all users on a system.
+                The <filename><envar>$HOME</envar>/.abuild/abuild.conf</filename> contains user-specific configuration, including the packager name and key pair path.  This allows multiple users to create their own repositories on a single system.
+                Configuration set in the <filename>/etc/abuild.conf</filename> will apply to all packages on the system unless overridden by the user-specific configuration file.</para>
+            <para>The most common configuration variables are explained below.  For a list of all available configuration variables, consult the <filename>abuild.conf(5)</filename> manual page by running <command>man 5 abuild.conf</command> on a computer where the <package>abuild-doc</package> package is installed.</para>
+            <variablelist>
+                <title><filename>abuild.conf</filename> Configuration Variables</title>
+                <varlistentry>
+                    <term><envar>CFLAGS</envar></term>
+                    <listitem><para><envar>CFLAGS</envar> contains the flags passed to the C compiler.  For more information about available flags, consult the documentation for your compiler.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><envar>CXXFLAGS</envar></term>
+                    <listitem><para><envar>CXXFLAGS</envar> contains the flags passed to the C++ compiler.  If <envar>CXXFLAGS</envar> is not set, and <envar>CFLAGS</envar> is set, then <envar>CXXFLAGS</envar> is set to the value of <envar>CFLAGS</envar>.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><envar>CPPFLAGS</envar></term>
+                    <listitem><para><envar>CPPFLAGS</envar> contains the flags passed to the C and C++ preprocessors.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><envar>LDFLAGS</envar></term>
+                    <listitem><para><envar>LDFLAGS</envar> contains the flags passed to the linker.  For more information about available flags, consult the documentation for your toolchain (likely <package>binutils</package>).</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><envar>JOBS</envar></term>
+                    <listitem><para><envar>JOBS</envar> should be set to the number of concurrent build processes you would like to run on your system.  Most dedicated build servers use a number equal to the number of CPU cores.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><envar>MAKEFLAGS</envar></term>
+                    <listitem><para><envar>MAKEFLAGS</envar> contains the flags passed to <command>make</command>.  The default value is <literal>-j$JOBS</literal>.  For more information about available flags, consult the documentation for <command>make</command>.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><envar>USE_COLORS</envar></term>
+                    <listitem><para><envar>USE_COLORS</envar> controls whether or not the <command>abuild</command> command will output colours to the terminal.  If you prefer a colourless output, or your terminal is not capable of ANSI colour codes, set this to <literal>0</literal>.  The default value is <literal>1</literal>.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><envar>SRCDEST</envar></term>
+                    <listitem><para><envar>SRCDEST</envar> should be an absolute path where source files are downloaded.  The default, and typical, value is <filename class="directory">/var/cache/distfiles</filename>.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><envar>REPODEST</envar></term>
+                    <listitem><para><envar>REPODEST</envar> should be an absolute path where finished packages are placed when built.  The default is <filename class="directory"><envar>$HOME</envar>/packages/</filename>.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><envar>PACKAGER</envar></term>
+                    <listitem><para>The value of <envar>PACKAGER</envar> is added to every produced package as the person responsible for packaging it.  Typically, this follows an RFC822-style "Name &lt;Email Address&gt;" format.  There is no default value; it must be set before running <command>abuild</command>.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><envar>PACKAGER_PRIVKEY</envar></term>
+                    <listitem><para><envar>PACKAGER_PRIVKEY</envar> should be an absolute path to the packager's private key, which will be used to sign every produced package.  Typically, this is set for you by the <command>abuild-keygen</command> command.  There is no default value; it must be set before running <command>abuild</command>.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><envar>MAINTAINER</envar></term>
+                    <listitem><para>The value of <envar>MAINTAINER</envar> is used as a point of contact if a user has an issue with a package, or if a security patch or update is available for the patch.  Typically, this follows an RFC822-style "Name &lt;Email Address&gt;" format.  The default value is the value of <envar>PACKAGER</envar>.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><envar>CLEANUP</envar></term>
+                    <listitem><para><envar>CLEANUP</envar> controls the cleanup procedure after a build that concludes with success.  The default value is <literal>srcdir pkgdir deps</literal>.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><envar>ERROR_CLEANUP</envar></term>
+                    <listitem><para><envar>ERROR_CLEANUP</envar> controls the cleanup procedure after a build that concludes with failure.  The default value is <literal>deps</literal>.</para></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><envar>DEFAULT_DBG</envar></term>
+                    <listitem><para><envar>DEFAULT_DBG</envar> controls whether a debug package will be created for compiled packages.  It is unset by default; being set to any value enables the option.  The typical value to enable the option is <literal>YesPlease</literal>.</para></listitem>
+                </varlistentry>
+            </variablelist>
+        </section>
+    </section>
+</chapter>
diff --git a/src/devel/2_nonpkg.xml b/src/devel/2_nonpkg.xml
new file mode 100644
index 0000000..c844be9
--- /dev/null
+++ b/src/devel/2_nonpkg.xml
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter label="2" id="nonpkg">
+    <title>Non-Package Development</title>
+    <para>There are a number of ways to contribute to the development of Adélie Linux that do not involve packaging.  This chapter will introduce you to other Adélie Linux projects and how to set up a development environment for each one.</para>
+    <section>
+        <title>Developing Adélie Documentation</title>
+        <para>In this section, you will learn:</para>
+        <itemizedlist>
+            <listitem><para>How documentation and guides like this one are authored; and</para></listitem>
+            <listitem><para>How you can configure your environment to edit and author documentation for Adélie Linux.</para></listitem>
+        </itemizedlist>
+        <section>
+            <title>Authorship of Documentation</title>
+            <para>The Adélie Linux Documentation Set, including the guide that you are reading, is written in a format called DocBook.  DocBook is somewhat similar to HTML in that it uses <firstterm>tags</firstterm> to define the semantics of the document, but the tags DocBook uses are different from HTML's and focus on creation of books and manuals.</para>
+            <para>The main Documentation Set is written in English, but we are happy to accept translations of our documentation into other languages.</para>
+            <para>You can contribute corrections, additions, or translations of any portion of our documentation by emailing the adelie-docs mailing list with your patch, or by creating a merge request on the Documentation GitLab page.  For more information about using Git to create patches and merge requests, see chapter 3.</para>
+        </section>
+        <section>
+            <title>Configuring Your Environment</title>
+            <para>You will need to install the <package>xmlto</package> package to ensure your changes leave the documentation syntatically valid.  After making your changes, run the <command>xmlto</command> command on the primary file (for this guide, <filename>develguide.xml</filename>) and ensure there are no errors.</para>
+        </section>
+    </section>
+    <section>
+        <title>Spread the Word</title>
+        <para>There are many ways to spread the word about Adélie Linux.
+            Talk to your friends about Adélie Linux and the benefits of libre software, including security, speed, and less need to purchase new computers every year.
+            Have civil discussions on forums, newsgroups, and social media.
+            If you're a student, talk to your school's Computer Science department and see if they are interested in a lab with Adélie Linux.
+            By spreading the word, you're helping more people learn and spreading our ideas and goals worldwide.  Thank you!</para>
+    </section>
+</chapter>
diff --git a/src/devel/3_git.xml b/src/devel/3_git.xml
new file mode 100644
index 0000000..ed97eca
--- /dev/null
+++ b/src/devel/3_git.xml
@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter label="3" id="git">
+    <title>Git Basics</title>
+    <para>The majority of Adélie Linux projects are stored in a distributed version control system called Git.
+        In this chapter, we will see an overview of how Git works, find out where its documentation lives, and learn about Adélie-specific workflows in Git.</para>
+    <section>
+        <title>Getting Started with Git</title>
+        <para>In this section, you will learn:</para>
+        <itemizedlist>
+            <listitem><para>What Git and distributed version control systems provide;</para></listitem>
+            <listitem><para>How to configure Git for work on Adélie Linux projects; and</para></listitem>
+            <listitem><para>Where to find documentation about Git.</para></listitem>
+        </itemizedlist>
+        <section>
+            <title>What is Git?</title>
+            <para>A <firstterm>version control system</firstterm> is a system that keeps track of a collection of related files, called a <firstterm>repository</firstterm>, and how they change over time.
+                If you are familiar with <productname>Mac OS X</productname>'s Time Machine functionality, a version control system is similar to this; it keeps a record of each file, when it was changed, and who changed it.
+                The primary difference is that a version control system only saves records of files when you explicitly tell it to do so.  This saving of a record is called a <firstterm>commit</firstterm>, and the list of all commits is called a <firstterm>commit log</firstterm>.</para>
+            <para>A <firstterm>distributed version control system</firstterm> allows many people to have their own copies of the repository containing the full commit log.  When a person wants to provide their commits to others, they <firstterm>push</firstterm> their commits to a central server.
+                Typically, people work on their own <firstterm>branch</firstterm>, or private tree of files.  When a person pushes their changed branch to the central server, it allows them to <firstterm>merge</firstterm> other branches.</para>
+            <para><firstterm>Git</firstterm> is a distributed version control system that runs on many different kinds of computers, and is very popular in open source development.  The Adélie Linux distribution uses Git to track everything from the package repositories, to the documentation set, to libraries and other software written for Adélie Linux.</para>
+            <para>Git allows us to maintain a record of who has contributed to the project, the date they contributed, and what changes they contributed.  It is therefore very important that you configure Git on your system to have your name and email address, so that the commit log attributes you correctly.</para>
+        </section>
+        <section>
+            <title>Configuring Git</title>
+            <para>If you have not already done so, you must first provide your name and email address to Git.  You may do this by running the following two commands:</para>
+            <para><prompt>$</prompt> <command>git <parameter>config</parameter> <parameter>--global</parameter> <parameter>user.name</parameter> <userinput>"Your Name"</userinput></command></para>
+            <para><prompt>$</prompt> <command>git <parameter>config</parameter> <parameter>--global</parameter> <parameter>user.email</parameter> <userinput>"email@address.tld"</userinput></command></para>
+            <para>If you have a PGP key (used for signing electronic messages), and it is publicly known and cross-signed, you should additionally provide this to Git.  This will allow more provability that you are the one who created a commit.  You may do this by running the following two commands:</para>
+            <para><prompt>$</prompt> <command>git <parameter>config</parameter> <parameter>--global</parameter> <parameter>user.signingkey</parameter> <userinput>YourPublicKeyFingerprint</userinput></command></para>
+            <para><prompt>$</prompt> <command>git <parameter>config</parameter> <parameter>--global</parameter> <parameter>commit.gpgsign</parameter> <parameter>true</parameter></command></para>
+        </section>
+        <section>
+            <title>Learning More about Git</title>
+            <para>There are many helpful resources available for you to learn more about Git.
+                You may install the <package>git-doc</package> package on your Adélie computer for easy access to the built-in manuals.
+                Additionally, if you have access to the World Wide Web, you may read the freely-licensed Pro Git book at https://git-scm.com/book/en/v2.
+                There are also a number of mailing lists for starting out and working with Git.</para>
+        </section>
+    </section>
+    <section>
+        <title>Using Git with Adélie</title>
+        <para>In this section, you will learn:</para>
+        <itemizedlist>
+            <listitem><para>How the Adélie Linux distribution uses Git branches and commits;</para></listitem>
+            <listitem><para>How to write a good, informative commit message; and</para></listitem>
+            <listitem><para>A guideline on how frequently to make commits and merge requests.</para></listitem>
+        </itemizedlist>
+        <section>
+            <title>Using Branches</title>
+            <para>A <firstterm>branch</firstterm> is a self-contained copy of a project's files.  Using branches allow your changes to be reviewed quickly and, if approved, merged in to the Adélie Linux source quickly.
+                A branch should be a single "unit of work".  That is, a branch should have a single goal in mind.  Sometimes a branch can contain many commits; for instance, your goal may be "update the Gnome Office packages".  In that case, you would have at least one commit for each Gnome Office package.
+                However, sometimes a branch only needs one commit.  This can be useful for simple bug fixes, or bumping a single package's version.</para>
+            <para>Branches should have a name that reflects their goal.  A branch name such as <literal>bugfix</literal> or <literal>version</literal> is unclear and doesn't communicate the goal of the branch.  A branch name such as <literal>gnumeric-1.12.35-update</literal> or <literal>fix-boot-on-g3</literal> is clear and concisely states the branch goal.</para>
+            <para>If you are not currently an Adélie Linux developer, you will create the branches in your <firstterm>fork</firstterm>, which is a private copy of the repository that is owned by you.  If you are an Adélie Linux developer, you can create the branch in your own private fork or the main repository.  For more information about creating forks, see the GitLab documentation.</para>
+        </section>
+        <section>
+            <title>Commits</title>
+            <para>A commit message should have the following structure:</para>
+            <screenco>
+                <areaspec>
+                    <area id="commit_area" coords="1 1"/>
+                    <area id="commit_summary" coords="1 7"/>
+                    <area id="commit_detail" coords="3"/>
+                    <area id="commit_signedoff" coords="5"/>
+                    <area id="commit_acked" coords="6"/>
+                </areaspec>
+                <screen>area: summary of change
+
+Multi-line details of change, if necessary.
+
+Signed-off-by: Your Name &lt;email@address.tld&gt;
+Acked-by: Developer Name &lt;email@adelielinux.org&gt;
+                </screen>
+                <calloutlist>
+                    <callout arearefs="commit_area">
+                        <para>The area changed by the commit.  For source code, this is typically the module name (such as <filename>string</filename> or <filename>gnulib</filename>).  For packages, this is the full name of the package, such as <filename>user/dejagnu</filename>.</para>
+                    </callout>
+                    <callout arearefs="commit_summary">
+                        <para>A brief summary of the commit.  The summary line should be less than 60 characters, and be a concise summary of the change made.</para>
+                    </callout>
+                    <callout arearefs="commit_detail">
+                        <para>A detailed summary of the commit.  You may expand on the rationale for the commit, or provide more information than you could in the summary line.</para>
+                    </callout>
+                    <callout arearefs="commit_signedoff">
+                        <para>If you are not yet an Adélie Linux developer, use the <parameter>--signoff</parameter> parameter to <command>git</command> to reflect that you agree to the contribution guidelines of the repository.</para>
+                    </callout>
+                    <callout arearefs="commit_acked">
+                        <para>If you communicated with an Adélie Linux developer about this change before sending the commit, add the <literal>Acked-by</literal> line to reflect such.  This will make it easier for further review to continue.</para>
+                    </callout>
+                </calloutlist>
+            </screenco>
+            <para>There are a few different standards for how often you should commit your work, depending on the repository to which you are contributing.
+                Some repositories contain guidelines in their Contribution Guide, found in the <filename>CONTRIBUTING.rst</filename> file in the root of the repository.
+                As a general guideline, when you are working on a source code repository, each commit should be one "logical change".
+                This could be adding a new function to an API, or changing an algorithm and ensuring all other files have the updated algorithm.</para>
+            <para>Similarly, when you are working on a package repository, you should use one commit per package that you change.
+                For instance, if you "bump" or update the version of three packages, you would use one commit for each of the three packages, for a total of three commits.
+                This allows an Adélie Linux developer to review each package's change separately.
+                There are some reasons you may want a single commit to hold changes to multiple packages.
+                For example, if you are updating the license fields of many packages, you may want a single commit with a message similar to <literal>main/libx*: update licenses on X11 libraries</literal>.</para>
+        </section>
+    </section>
+</chapter>
diff --git a/src/devel/4_hello.xml b/src/devel/4_hello.xml
new file mode 100644
index 0000000..cc45af6
--- /dev/null
+++ b/src/devel/4_hello.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter label="4" id="hello">
+    <title>Writing Your First Package</title>
+    <para></para>
+    <section>
+        <title></title>
+        <para></para>
+    </section>
+</chapter>
diff --git a/src/devel/5_deepdive.xml b/src/devel/5_deepdive.xml
new file mode 100644
index 0000000..a0eac6b
--- /dev/null
+++ b/src/devel/5_deepdive.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter label="5" id="deepdive">
+    <title>Deep Dive in to <filename>APKBUILD</filename></title>
+    <para></para>
+    <section>
+        <title></title>
+        <para></para>
+    </section>
+</chapter>
diff --git a/src/devel/6_security.xml b/src/devel/6_security.xml
new file mode 100644
index 0000000..95008c0
--- /dev/null
+++ b/src/devel/6_security.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter label="6" id="security">
+    <title>Ensuring Security</title>
+    <para></para>
+    <section>
+        <title></title>
+        <para></para>
+    </section>
+</chapter>
diff --git a/src/devel/7_misc.xml b/src/devel/7_misc.xml
new file mode 100644
index 0000000..f806ab7
--- /dev/null
+++ b/src/devel/7_misc.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter label="7" id="misc">
+    <title>Odds and Ends</title>
+    <para></para>
+    <section>
+        <title></title>
+        <para></para>
+    </section>
+</chapter>
diff --git a/src/devel/8_help.xml b/src/devel/8_help.xml
new file mode 100644
index 0000000..4f43069
--- /dev/null
+++ b/src/devel/8_help.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter label="8" id="help">
+    <title>If You Need Help</title>
+    <para></para>
+    <section>
+        <title></title>
+        <para></para>
+    </section>
+</chapter>
diff --git a/src/devel/develguide.xml b/src/devel/develguide.xml
new file mode 100644
index 0000000..8447c80
--- /dev/null
+++ b/src/devel/develguide.xml
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+               <!ENTITY chap1 SYSTEM "1_preparing.xml">
+               <!ENTITY chap2 SYSTEM "2_nonpkg.xml">
+               <!ENTITY chap3 SYSTEM "3_git.xml">
+               <!ENTITY chap4 SYSTEM "4_hello.xml">
+               <!ENTITY chap5 SYSTEM "5_deepdive.xml">
+               <!ENTITY chap6 SYSTEM "6_security.xml">
+               <!ENTITY chap7 SYSTEM "7_misc.xml">
+               <!ENTITY chap8 SYSTEM "8_help.xml">
+]>
+<book>
+    <bookinfo>
+        <title>Adélie Linux 1.0 Developer's Guide</title>
+        <author>
+            <personname><firstname>A.</firstname><surname>Wilcox</surname></personname>
+        </author>
+        <copyright><year>2017</year><holder>Adélie Linux</holder></copyright>
+    </bookinfo>
+    <preface>
+        <title>Preface</title>
+        <para>This Developer's Guide is the official guide to developing the Adélie Linux 1.0 system.  It is designed for developers interested in working on the distribution itself; for general information on programming your computer running the Adélie Linux system, see the User's Guide chapter "Getting started with programming".</para>
+        <para>Many contributed to the final version of this guide.  This includes <personname><firstname>Natanael</firstname><surname>Copa</surname></personname> and <personname><firstname>Timo</firstname><surname>Teras</surname></personname> from Alpine Linux.</para>
+        <para>It is assumed that you, the reader, are familiar with using a terminal or command line interface, the use of Unix commands, and the compilation of software.  If you are not yet familiar with these concepts, start with our User's Guide, which will assist you in learning them.</para>
+        <para>Please also ensure that you are comfortable and properly rested before reading this guide.  This will allow you to learn quicker, and be able to recall the information you have learned easier.</para>
+        <para>It is hoped by the author that you find this guide easy to understand and read.  Please feel free to contact me or the Adélie Linux community if you have any suggestions on how to make this guide better.  We'd love to hear from you, and we hope you enjoy using our distribution.</para>
+        <para>– A. Wilcox, 2017</para>
+    </preface>
+    &chap1;
+    &chap2;
+    &chap3;
+    &chap4;
+    &chap5;
+    &chap6;
+    &chap7;
+    &chap8;
+</book>