diff options
| -rw-r--r-- | CONTRIBUTING.rst | 72 | ||||
| -rw-r--r-- | README.rst | 120 |
2 files changed, 189 insertions, 3 deletions
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 0000000..974be6a --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,72 @@ +======================================== + Contribution Guide for Project Horizon +======================================== +:Author: + * **A. Wilcox**, documentation writer +:Copyright: + © 2015-2019 Adélie Linux Team. NCSA open source licence. + + + + +Contributing Changes +==================== + +This section describes the usual flows of contribution to this repository. +For a detailed description of how to contribute to Adélie Linux, review the +Handbook_. + +.. _Handbook: https://help.adelielinux.org/html/devel/ + + +GitLab Pull Requests +```````````````````` + +#. If you do not already have a GitLab account, you must create one. + +#. Create a *fork* of the Horizon 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 commands ``git commit -S`` 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 Horizon 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 -S``. + +#. 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 mailing list, using ``git send-email`` or + your mail client. Ensure you are subscribed_ first. + +.. _subscribed: https://lists.adelielinux.org/postorius/lists/horizon.lists.adelielinux.org/ @@ -9,14 +9,26 @@ * **Zach van Rijn**, design and requirements * **Alyx Wolcott**, analyst assistant :Status: - Requirements Phase + Development :Copyright: © 2015-2019 Adélie Linux. - Code: NCSA license. + Code: AGPL-3.0 license. Documentation: CC BY-NC-SA open source license. +Project Horizon is the next-generation installation system for Adélie Linux. +It provides everyone with tools that make installation easy, inspectable, +auditable, secure, and fast. + +.. image:: https://img.shields.io/badge/chat-on%20IRC-blue.svg + :target: ircs://irc.interlinked.me:6697/#Adelie-Support + +.. image:: https://img.shields.io/badge/license-AGPL3-lightgrey.svg + :target: LICENSE-code + + + Introduction ============ @@ -32,10 +44,112 @@ Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. You should have received a copy of the license along with this work. If not, see <http://creativecommons.org/licenses/by-nc-sa/4.0/>. -Code is licensed under the Adélie-standard NCSA license. +Code is licensed under the Affero GPL (AGPL) 3 license. Changes ``````` Any changes to this repository must be reviewed before being pushed to the master branch. + + + +If You Need Help +================ + +This repository is primarily for system developers. If you're looking for +help using or installing Adélie Linux, see `our Help Centre on the Web`_. + +.. _`our Help Centre on the Web`: https://help.adelielinux.org/ + + + +Repository Layout +================= + +Project Horizon is laid out into multiple directories for ease of maintenance. + +``build``: Build system artefacts +````````````````````````````````` +The ``build`` directory contains build output, including binaries and shared +libraries. + + +``devel``: Development information +`````````````````````````````````` +The ``devel`` directory contains the Vision document, the Functional Software +Requirements Specification for Project Horizon, and the official HorizonScript +Specification. The documents are written in DocBook XML; the HTML and PDF +versions are not stored in this repository. + + +``hscript``: HorizonScript library +`````````````````````````````````` +The ``hscript`` directory includes the source code for the HorizonScript +library. This is the primary library for parsing, validating, and executing +HorizonScript files, and contains the principal code for Project Horizon. + + +``tools``: Tooling and accessories +`````````````````````````````````` +The ``tools`` directory includes the source code for tools related to Project +Horizon, including: + +* The Validation Utility, which allows you to validate manually written + installfiles. + +* The Simulator, which allows you to view how the Horizon Runner would + interpret your installfile. The Simulator additionally allows you to + output the interpretation of your installfile to a shell script. + + +``util``: Shared utility code +````````````````````````````` +The ``util`` directory includes source code that is common between libraries +and tools. + + +``tests``: Test infrastructure +`````````````````````````````` +The ``tests`` directory includes the ``fixtures`` directory, which is a +collection of dozens of example installfiles that exercise the parsing +and validation code of libhscript. Some of these installfiles are +purposefully invalid, and others contain edge cases to ensure that the +library is written and implemented correctly. + +It also contains the ``spec`` directory, which is a series of RSpec tests +designed to use the fixtures and ensure the correct output is given. + + +``3rdparty``: External code +``````````````````````````` +The ``3rdparty`` directory contains vendored code. Currently, this is only +the clipp_ project, used by the ``tools`` for argument parsing. + +.. _clipp: https://github.com/muellan/clipp + + + +Contributing +============ + +See the CONTIRIBUTING.rst_ file in the same directory as this README for +more details on how to contribute to Project Horizon. + +.. _CONTRIBUTING.rst: CONTRIBUTING.rst + + + +Reporting Issues +================ + +If you have an issue using Project Horizon, you may view our BTS_. You may +also `submit an issue`_ directly. + +For general discussion, questions, or to submit a patch, please use the +`Horizon mailing list`_. + +.. _BTS: https://bts.adelielinux.org/buglist.cgi?product=Horizon&resolution=--- +.. _`submit an issue`: https://bts.adelielinux.org/enter_bug.cgi?product=Horizon +.. _`Horizon mailing list`: https://lists.adelielinux.org/postorius/lists/horizon.lists.adelielinux.org/ + |