path: root/CONTRIBUTING.rst

=================================================
 Contribution Guide for Adélie Linux Package Set
=================================================
:Author:
  * **Andrew Wilcox**, documentation writer
:Status:
  Draft
:Copyright:
  © 2016 Wilcox Technologies LLC.  NCSA open source licence.




Introduction
============

This repository contains the Adélie Linux package set.  It is used as an
overlay in the Portage system for package building to create the repository
used by Adélie's APK package manager.


Licenses
`````````
As the Adélie Linux project is an open-source Linux distribution, packages
contained in this repository must also be provided under a license recognised
by the OSI_.  A separate repository may be provided in the future for certain
non-free components, such as device driver firmware.

.. _OSI: http://opensource.org/licenses/category


Changes
```````
Any changes to this repository - additions, removal, or version bumps - 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.




Ebuild Format
=============

This section describes the Ebuild format required for packages in this
repository.


EAPI
````

Any Ebuild present in this repository **must** use EAPI 5.  As EAPI 6 is not
yet supported by any publicly released version of the Portage toolkit, it is
not yet acceptable for use in this repository.


Source URIs
```````````

It is recommended that any Ebuild present in this repository use an official
Adélie Linux mirror for any files downloaded (``mirror://adelie/``).
Exceptions will be granted on a case-by-case basis for issues such as file
size or rapid version change.


Comments
````````

It is highly encouraged that you use comments in your Ebuild.  This grants
other developers and the Adélie Linux team the same level of understanding
that you have over the package.  Any issues found that cause behaviour
deviant from the eclass defaults should have an explanation and/or link to
a problem report (either upstream or on http://bts.adelielinux.org/).


Custom Eclasses
```````````````

If you require a custom Eclass not already present in the base Portage tree
or this repository, please file a problem report on http://bts.adelielinux.org/
with an explanation of what your Eclass will provide.  A test suite in the
form of various Ebuilds demonstrating proper behaviour and failure modes will
be greatly appreciated and raise the likelihood of a speedy addition to the
tree.  Please do **not** file a pull request containing a new Eclass without
filing a problem report first.




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 ``repoman commit``.

#. 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 ``repoman 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.