Initial commit with documentation

3 files changed, 269 insertions, 0 deletions

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
new file mode 100644
index 0000000..f12bc83
--- /dev/null
+++ b/CONTRIBUTING.rst
@@ -0,0 +1,156 @@
+===============================
+ Contribution Guide for Shimmy
+===============================
+:Author:
+  * **Andrew Wilcox**, documentation writer
+:Status:
+  Draft
+: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.
+
+
+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.
+
+
+
+
+Adding a New Utility
+====================
+
+The addition of more compliant utilities is always appreciated.  If you would
+like to contribute one, please ensure that:
+
+* the utility in question is specified in IEEE Std 1003.1, 2013 Edition
+  (Issue 7);
+
+* you have created a new directory in the top level named after the utility;
+
+* you have included an appropriate man page for it in the directory;
+
+* and it compiles cleanly on a strictly compliant POSIX® environment.
+
+Note that strictly compliant POSIX® software may include shims to compile on
+non-compliant systems as well - the only requirement is that they *can* be
+compiled on strictly compliant systems with no changes, and that they do not
+rely on unspecified interfaces or return values.
+
+
+
+
+Testing
+=======
+
+You **must** test any changes on Adélie Linux.  It is recommended that you
+additionally test your changes on at least a glibc-based Linux distribution.
+
+You are welcome to test on a Berkeley Software Distribution.  Please note
+however that they are not POSIX® compliant and may require some changes to
+ensure build success.
+
+You are additionally welcome to test on Mac OS X, Solaris, AIX, and HP-UX.
+However, some of these systems deviate from POSIX® in some APIs or do not fully
+implement every option.  Care should be taken when testing on these systems.
+
+
+
+
+Extensions
+==========
+
+Some extensions, such as BSD or GNU, can be useful in some situations.  We will
+review extensions on a case-by-case basis.  Please do note that extensions that
+directly conflict with the POSIX® specification (that is, where implementation
+of said extension would cause loss of compliance with POSIX®) will never be
+accepted in tree.
+
+
+
+
+Contributing Changes
+====================
+
+This section describes the usual flows of contribution to this repository.
+
+
+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 command ``git commit`` 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``.
+
+#. 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 packagers mailing list.
+
+
+
+
+Legal Notice
+============
+
+POSIX® is a registered trademark of the IEEE.  While we aim to provide utilities
+that meet the POSIX® specification, this package has not yet been submitted to
+the Open Group for testing, and thus cannot be termed as "POSIX® compliant" in
+any documentation.  Instead, use "POSIX® conformant".
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..64309ae
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,32 @@
+Copyright (c) 2016 Adélie Linux Team.
+All rights reserved.
+
+Developed by: 		Adélie Linux Team
+                        http://adelielinux.org/
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal with the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject
+to the following conditions:
+
+Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimers.
+
+Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimers in
+the documentation and/or other materials provided with the distribution.
+
+Neither the names of Adélie Linux, nor the names of its contributors, may
+be used to endorse or promote products derived from this Software without
+specific prior written permission.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE.
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.