1 files changed, 81 insertions, 0 deletions
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..08b4fc5
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,81 @@
+===================
+ README for Shimmy
+===================
+:Authors:
+  * **Andrew Wilcox**, primary developer
+  * **Elizabeth Myers**, developer, QA
+:Status:
+  Beta
+:Copyright:
+  © 2016 Adélie Linux.  NCSA open source licence.
+
+
+
+
+Introduction
+============
+
+This repository contains code and documentation for Shimmy, a small set of
+utilities designed to bring stricter POSIX® compliance to open-source operating
+environments.  It is designed mainly for use on Adélie Linux, but it is also
+occasionally tested on Gentoo Linux, FreeBSD, OpenBSD, and Mac OS, among others.
+
+Note that for ideal compliance, you need to perform any *one* of the following
+tasks:
+
+* Install these utilties to a path listed in your system's _CS_PATH (typically,
+  this is only /bin and /usr/bin).
+
+* *or* ensure that the directory where Shimmy is installed comes first in PATH,
+  and that getconf(1) PATH returns the directory as well, typically by patching
+  it.
+
+
+License
+```````
+
+As the Adélie Linux project is an open-source Linux distribution, this package
+is distributed under the same NCSA open source license as the distribution.
+
+
+Changes
+```````
+
+Any changes to this repository 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.
+
+
+
+
+Included utilities
+==================
+
+This section contains information about the utilities included with the Shimmy
+package.
+
+
+getconf(1)
+``````````
+
+The getconf(1) utility returns configuration information about the presently
+running operating environment using sysconf(3), confstr(3), and fpathconf(3).
+
+With the exception of OpenBSD, almost all tested targets had at least one
+issue with strict POSIX® conformance.
+
+* FreeBSD returned "Invalid argument" on _POSIX_TRACE_LOG, instead of the
+  expected result "undefined" or "-1".
+
+* glibc returned "Unrecognised variable" for V7_ENV when it has a defined value
+  in glibc's confstr(3) implementation.  It also considers _POSIX_MAX_INPUT and
+  MAX_INPUT as the same variable, which is incorrect (the former being the total
+  maximum implementation value, and the latter being the maximum value for a
+  specified terminal file).
+
+* musl does not ship a getconf; however, Alpine Linux ships a getconf utility.
+  It is heavily obsolescent (being based on 1997 NetBSD code).  It does not
+  recognise _XOPEN_* variables nor does it recognise _-prefixed POSIX2
+  variables.
+
+* NetBSD does not recognise _-prefixed POSIX2 variables.