Add documentation for the repository

3 files changed, 176 insertions, 0 deletions

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
new file mode 100644
index 0000000..d9ab608
--- /dev/null
+++ b/CONTRIBUTING.rst
@@ -0,0 +1,100 @@
+====================================================
+ Contribution Guide for Adélie Linux Build Software
+====================================================
+:Author:
+  * **A. Wilcox**, documentation writer
+:Status:
+  Production
+:Copyright:
+  © 2019 Adélie Linux Team.  NCSA open source licence.
+
+
+
+
+Introduction
+============
+
+This repository contains the software used to build the Adélie Linux package
+set.  It is used by Adélie Linux for package building to create the repository
+used by Adélie's APK package manager.
+
+
+Changes
+```````
+Any changes to this repository - additions, removal, or version bumps - must
+be reviewed before being pushed to the master branch.  There are no exceptions
+to this rule.  For security-sensitive updates, contact the Security Team at
+sec-bugs@adelielinux.org.
+
+
+
+
+Source Code Format
+==================
+
+Shell scripts must be as close to POSIX Shell as possible.  Bash extensions
+are explicitly not allowed.
+
+
+
+
+Contributing Changes
+====================
+
+This section describes the usual flows of contribution to this repository.
+For a detailed description of how to contribute to Adélie Linux, review the
+Handbook_.
+
+.. _Handbook: https://help.adelielinux.org/html/devel/
+
+
+GitLab Pull Requests
+````````````````````
+
+#. If you do not already have a GitLab account, you must create one.
+
+#. Create a *fork* of the packages repository.  For more information, consult
+   the GitLab online documentation.
+
+#. Clone your forked repository to your computer.
+
+#. Make your changes.
+
+#. Test your changes to ensure they are correct.
+
+#. Add (or remove) changed files using ``git add`` and ``git rm``.
+
+#. Commit your changes to the tree using the commands ``git commit -S`` and
+   ``git push``.
+
+#. Visit your forked repository in a Web browser.
+
+#. Choose the *Create Pull Request* button.
+
+#. Review your changes to ensure they are correct, and then submit the form.
+
+
+Mailing List
+````````````
+
+#. Clone the packages repository to your computer.
+
+#. Make your changes.
+
+#. Test your changes to ensure they are correct.
+
+#. Add (or remove) changed files using ``git add`` and ``git rm``.
+
+#. Commit your changes to the tree using the command ``git commit -S``.
+
+#. Use the command ``git format-patch HEAD^`` to create a patch file for your
+   commit.
+
+   .. note:: If you have made multiple commits to the tree, you will need to
+             add an additional ^ for each commit you have made.  For example,
+             if you have made three commits, you will use the command
+             ``git format-patch HEAD^^^``.
+
+#. Email the resulting patch to the mailing list, using ``git send-email`` or
+   your mail client.  The mailing list is adelie-devel, on the
+   lists.adelielinux.org mailman server.
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..17d90db
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,5 @@
+Some code in this repository is licensed under MIT:
+
+* abuild-fetch.c
+
+Everything else is GPL-2.0-only.
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..3ccbe17
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,71 @@
+========================================
+ README for Adélie Linux Build Software
+========================================
+:Authors:
+  * **A. Wilcox**, Distro Lead
+  * **Adélie Linux Developers and Users**, contributions
+:Status:
+  Production
+:Copyright:
+  © 2019 Adélie Linux Team.  Mix of MIT and GPL 2 open source licences.
+
+
+
+
+Introduction
+============
+
+This repository contains the software used to build the Adélie Linux package
+set.  It is used by Adélie Linux for package building to create the repository
+used by Adélie's APK package manager.
+
+
+Licenses
+`````````
+Most of the code in this repository is licensed GPL-2.0-only.  The
+``abuild-fetch`` applet is licensed under the MIT license.
+
+
+Changes
+```````
+Any changes to this repository - additions, removal, or version bumps - must
+be reviewed before being pushed to the master branch.  There are no exceptions
+to this rule.  For security-sensitive updates, contact the Security Team at
+sec-bugs@adelielinux.org.
+
+
+
+
+Contents
+========
+
+This section contains a high-level view of the contents of this repository.
+
+
+``abuild-fetch``: Download package sources
+``````````````````````````````````````````
+The ``abuild-fetch`` applet is used to download package sources from the
+Internet.
+
+
+``abuild-tar``: Archive manipulation
+````````````````````````````````````
+The ``abuild-tar`` applet is used to manipulate ``tar`` files into ``APK``
+files.  More on the APK file format is discussed on our wiki_.
+
+.. _wiki: https://wiki.adelielinux.org/wiki/APK_internals
+
+
+``abuild``: Package building
+````````````````````````````
+The ``abuild`` script is the script responsible for building packages.
+
+
+``newapkbuild``: Package recipe creation
+````````````````````````````````````````
+The ``newapkbuild`` script is used to create new package recipes, called
+``APKBUILD`` files.  More information can be found in the Handbook_ or the
+man page installed with the ``abuild-doc`` package (``man 5 APKBUILD``).
+
+.. _Handbook: https://help.adelielinux.org/html/devel/
+