===============================
Contribution Guide for Shimmy
===============================
:Author:
* **A. Wilcox**, documentation writer
:Status:
Draft
:Copyright:
© 2016 Adélie Linux Team. 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".
