Contribution Guide for Shimmy
|Copyright:||© 2016 Adélie Linux Team. NCSA open source licence.|
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.
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.
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 email@example.com.
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.
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.
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.
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
- Commit your changes to the tree using the command
- 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.
Clone the packages repository to your computer.
Make your changes.
Test your changes to ensure they are correct.
Add (or remove) changed files using
Commit your changes to the tree using the command
Use the command
git format-patch HEAD^to create a patch file for your commit.
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.
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".