Commit 3fbd8c32 authored by A. Wilcox's avatar A. Wilcox 🦊
Browse files

Initial commit with documentation

parents
===============================
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".
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.
===================
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.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment