add docs/

5 files changed, 118 insertions, 0 deletions

diff --git a/docs/format-abs.md b/docs/format-abs.md
new file mode 100644
index 0000000..c87e1b1
--- /dev/null
+++ b/docs/format-abs.md
@@ -0,0 +1,23 @@
+# Format: ABS (Arch Build System)
+
+## The skinny
+
+ * SVN-based
+ * Used by the Arch Linux developers.
+ * Canonically hosted at
+   svn://svn.archlinux.org/packages
+
+## Details
+
+ABS is an SVN-versioned flat directory tree.
+
+ * `/<pkgbase>/trunk/`
+   The "working copy" of `<pkgbase>`.
+ * `/<pkgbase>/repos/<repo>-<arch>/`
+   The version of <pkgbase> that is currently available on the
+   repository `<repo>` (eg, `core`, `extra`) for `<arch>`
+   architecture.
+
+The developers themselves only make changes to `/<pkgbase>/trunk/`
+directories, and `/<pkgbase>/trunk/` directories are maintained by
+devtools/dbscripts.
diff --git a/docs/format-absgit.md b/docs/format-absgit.md
new file mode 100644
index 0000000..f8cb02a
--- /dev/null
+++ b/docs/format-absgit.md
@@ -0,0 +1,25 @@
+# Format: ABSgit (ABS on git)
+
+## The skinny
+
+ * git-based
+ * Generated by running ABS through `svn2git`
+ * Canonically hosted at
+   git://projects.archlinux.org/svntogit/packages.git
+
+## Details
+
+ABSgit can be treated like ABS, but with git instead of SVN, if you
+only look at the `master` branch, which I will remind you is
+
+ * `/<pkgbase>/trunk/`
+   The "working copy" of `<pkgbase>`.
+ * `/<pkgbase>/repos/<repo>-<arch>/`
+   The version of <pkgbase> that is currently available on the
+   repository `<repo>` (eg, `core`, `extra`) for `<arch>`
+   architecture.
+
+However, it gives us a bunch of "convenience" branches.  Each
+`<pkgbase>` directory is available by itself as the branch
+`packages/<pkgbase>`.  HOWEVER, there may not be a separate branch for
+a directory if that directory is not present in `HEAD`.
diff --git a/docs/format-abslibre.md b/docs/format-abslibre.md
new file mode 100644
index 0000000..2f4e86e
--- /dev/null
+++ b/docs/format-abslibre.md
@@ -0,0 +1,13 @@
+# Format: ABSLibre (ABS Libre)
+
+## The skinny
+
+ * git-based
+ * Is the "abstree" format, but versioned with git
+ * Used by Parabola
+ * Canonically hosted at
+   git://parabolagnulinux.org/abslibre/abslibre.git
+
+## Details
+
+This is the "abstree" format, but versioned in git.
diff --git a/docs/format-abstree.md b/docs/format-abstree.md
new file mode 100644
index 0000000..e023ab0
--- /dev/null
+++ b/docs/format-abstree.md
@@ -0,0 +1,16 @@
+# Format: ABStree (ABS tree)
+
+## The skinny
+
+ * non-versioned
+ * What most users know as "ABS"
+ * The `abs` command syncs this to `/var/abs/` (by default)
+ * Maintained by dbscripts
+
+## Details
+
+This is a flat directory tree, with the structure
+
+ * `<repo>/<pkgbase>`
+   The copy of `<pkgbase>` as it is available in `<repo>` for your
+   architecture.
diff --git a/docs/format-pbs.md b/docs/format-pbs.md
new file mode 100644
index 0000000..4d75f7c
--- /dev/null
+++ b/docs/format-pbs.md
@@ -0,0 +1,41 @@
+# Format: PBS (Parabola Build System)
+
+## The skinny
+
+ * git-based (heavily)
+ * Designed to have the UX of abstree/abslibre, but the capabilities
+   of ABS
+
+## Details
+
+PBS is designed to look like ABS-tree, that is, a directory tree with
+directories of the format:
+
+    /<repo>/<pkgbase>
+
+In addition to this, there is a `/.pbs-root` file to identify the root
+directory of the PBS repository.
+
+There are several branches; `master` is where development happens, and
+there is a branch with the name of each architecture, which (should)
+reflect what is currently available from the pacman repositories.
+
+Where this really differs from ABS-tree is that each `<pkgbase>`
+directory is actually a git submodule.  Despite being submodules, they
+live in the same git repository; the default remote for them is the
+git repository that they are submodules of.  That is, in
+`.gitmodules`, the `url = ./` for each submodule.
+
+Each package submodule there exists a file `.pbs-package` to identify
+that directory as the root of a package.
+
+In a package submodule there may be a `pbstrack` file with the format
+
+    <git-remote-repository> packages/<pkgbase>
+
+(or equivalently)
+
+    <git-remote-repository> <git-remote-branch>
+
+that identifies a package that it is downstream/forked from, and can
+be used to get updates.