Initial commit with documentation

1 files changed, 156 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".