From 3fbd8c3210ac6d26f5518b0fca60c48d29cee421 Mon Sep 17 00:00:00 2001 From: Andrew Wilcox Date: Sat, 9 Apr 2016 11:31:05 -0500 Subject: Initial commit with documentation --- CONTRIBUTING.rst | 156 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ LICENSE | 32 ++++++++++++ README.rst | 81 +++++++++++++++++++++++++++++ 3 files changed, 269 insertions(+) create mode 100644 CONTRIBUTING.rst create mode 100644 LICENSE create mode 100644 README.rst 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. -- cgit v1.2.3-60-g2f50