diff --git a/CODESTYLE.rst b/CODESTYLE.rst new file mode 100644 index 0000000..449dece --- /dev/null +++ b/CODESTYLE.rst @@ -0,0 +1,9 @@ +Code style requirements for TurnKey Linux +========================================= + +This doc is a placeholder for our WIP code style requirements. + +Until we have a document of substance, this will be maintained as a `GH wiki +page`_. + +.. _GH wiki page: https://github.com/turnkeylinux/tracker/wiki/Code-styling diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c2dbd9e..a332345 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,9 @@ -#Contributing to TurnKey +# Contributing to TurnKey The following is a consolidated series of guidelines for contributions to TurnKey Linux (TKL). These guidelines are derived from a number of existing documents that are currently spread across GitHub and the [documentation](https://www.turnkeylinux.org/docs) section of the TKL website. If you feel that these guidelines are lacking, feel free to make changes as you see fit. -##Contents +## Contents [General Information](#general-information) * [About TurnKey Linux](#about-turnkey-linux) @@ -16,7 +16,7 @@ The following is a consolidated series of guidelines for contributions to TurnKe ## General Information -###About TurnKey Linux +### About TurnKey Linux TurnKey GNU/Linux is an open source library of Debian based system images packaged as virtual appliances. Virtual appliances function as self contained systems that are capable of running on industry standard hardware or virtual machines created through software such as Virtualbox. Consult [this guide](https://www.turnkeylinux.org/docs/installation-appliances-virtualbox-new) for a basic overview on how to install virtual appliances. @@ -26,36 +26,36 @@ All TKL source code is managed by [Git](https://git-scm.com/documentation) and h Developers with good ideas are encouraged to be bold and contribute code. -###Development Toolchain +### Development Toolchain * [TKLDev](https://www.turnkeylinux.org/tkldev): This is the recommended tool for appliance development. As "the mother of all TurnKey apps", TKLDev is a self contained appliance that is capable of rapidly prototyping new Linux distributions and building existing integrations from source material. For more detailed information on using this appliance, consult the docs in the [TKLDev repository](https://github.com/turnkeylinux-apps/tkldev/tree/master/docs) here on GitHub. * [TKLPatch](https://www.turnkeylinux.org/docs/tklpatch): A set of shell scripts that may be used to customize and extend existing virtual appliances. While recent versions of TKLDev enable the creation of appliances from source, TKLPatch may still be used for light customization. -##Contributing +## Contributing -###Gitflow +### Gitflow -Development of TKL is loosely based on [GitHub Flow](http://scottchacon.com/2011/08/31/github-flow.html), a widely accepted set of guidelines for contributing to projects over GitHub. As such, TKL development follows these basic guidelines: -* Anything in the master branch is deployable (builds that have successfully been proven to work) -* When working on something new (ie: a bugfix or a new feature), create a descriptively named branch off of the master. Each new branch should address a single issue. -* Commit to that branch locally and regularly. Source code should be documented and rational for changes included in commits. +Development of TKL is loosely based on [GitHub Flow](http://scottchacon.com/2011/08/31/github-flow.html), a widely accepted set of guidelines for contributing to projects over GitHub. As such, TKL development follows these basic guidelines: +* Anything in the master branch is deployable (builds that have successfully been proven to work). +* When working on something new (ie: a bugfix or a new feature), create a descriptively named branch off of the master. Each new branch should address a single issue. +* Commit to that branch locally and regularly. Source code should be documented and rationale for changes included in commits. * Open a pull request for help, feedback or branch merging. * Once someone else has reviewed and signed off on the changes, the project maintainer or a core developer will merge it with the official repository. -* Once it is merged and pushed to the master, the project should be rebuilt and released immediately. +* Once it is merged and pushed to the master, the project should be rebuilt and released immediately. -Collaboration is facilitated over GitHub through the use of [fork](https://help.github.com/articles/fork-a-repo/) and [pull requests](https://help.github.com/articles/using-pull-requests/).In order to make use of these features, developers will need to [create a GitHub account]() and add their SSH public key if they have not already done so. +Collaboration is facilitated over GitHub through the use of [fork](https://help.github.com/articles/fork-a-repo/) and [pull requests](https://help.github.com/articles/using-pull-requests/). In order to make use of these features, developers will need to [create a GitHub account]() and add their SSH public key if they have not already done so. -###Contribution Walkthrough +### Contribution Walkthrough **Fork and clone source:** * To begin, login and find a repository that you would like to work on. -* Within the desired repository, press the ``fork`` button to fork the repository. +* Within the desired repository, press the ``fork`` button to fork the repository. * The repository will then need to be cloned before you can work on it. You can do so with this snippet of code: `git clone git@github.com:USERNAME/PROJECTNAME.git` * Once the repository has been cloned, it will have a ``remote`` called ``origin``. This will point to your newly created fork on GitHub rather than the original repository. -*You will need to add another ``remote`` in order to keep track of the original repository. In this example, it will be called ``upstream``: +* You will need to add another ``remote`` in order to keep track of the original repository. In this example, it will be called ``upstream``: ``` cd PROJECTNAME @@ -79,27 +79,27 @@ git merge upstream/master Now that you're finished and all changes are committed, you need to push them to your GitHub repository: - `git push origin DESCRIPTIVE_BRANCH_NAME` + git push origin DESCRIPTIVE_BRANCH_NAME -Finally, submit a ``pull request``so that the maintainer or a core developer may review your changes and merge them into the official repository.If for some reason the maintainer or one of the core developers has a problem with your change, they won't want to merge until fixed. However, whenever you commit and push more changes to that branch of your code, they will be included in that original pull request until it is closed. +Finally, submit a ``pull request`` so that the maintainer or a core developer may review your changes and provide necessary feedback. Further commits pushed into the same branch will be automatically included in your ``pull request`` until it is closed. Upon successfull review your changes will be merged into the official repository. -###Bug Reports and feature requests +### Bug Reports and feature requests -TKL uses GitHub's project management features to track development. Included in these features are the [issue tracker](https://github.com/turnkeylinux/tracker/issues/) (used to report bugs and record feature requests) and the [Wiki](https://github.com/turnkeylinux/tracker/wiki) (used to propose and track appliance candidates and as a general purpose whiteboard for TKL development). +TKL uses GitHub's project management features to track development. Included in these features are the [issue tracker](https://github.com/turnkeylinux/tracker/issues/) (used to report bugs and record feature requests) and the [Wiki](https://github.com/turnkeylinux/tracker/wiki) (used to propose and track appliance candidates and as a general purpose whiteboard for TKL development). Before opening a new issue, please check to see if a similar bug, issue or feature request already exists in the tracker. If a similar topic is currently open, post a comment stating that it also affects you. Knowing an issue affects multiple users is useful when we decide how to prioritize limited development resources. Please try and include any additional information you think might help us close the issue. The ideal bug / issue report includes: -* A detailed description of the bug / issue -* Step by step instructions on how it may be reproduced -* the output that is generated from using the ``turnkey-version`` command, which should look like this: +* A detailed description of the bug / issue. +* Step by step instructions on how it may be reproduced. +* The output that is generated from using the ``turnkey-version`` command, which should look like this: ``` turnkey-appliance_name-major_version.minor_version-debian_codename-architecture ``` The ideal feature request includes: -* A detailed description of the feature and the component it relates to -* One or more cases in which the feature might be of use -* Any other relevant information +* A detailed description of the feature and the component it relates to. +* One or more cases in which the feature might be of use. +* Any other relevant information. -Note that the tracker is not intended to for use as a forum for support or general discussion. For technical support or general discussion, please use the appropriate [forum](https://www.turnkeylinux.org/forum). +Note that the tracker is not intended to be used as a forum for support or general discussion. For technical support or general discussion, please use the appropriate [forum](https://www.turnkeylinux.org/forum). diff --git a/GITFLOW.rst b/GITFLOW.rst index a7bf187..3161a7b 100644 --- a/GITFLOW.rst +++ b/GITFLOW.rst @@ -28,7 +28,7 @@ follows these guidelines: should address just one issue (i.e. create a separate branch from master for each issue). * Commit to that branch locally and regularly. Source code should be - documented and rational for changes included in commits. + documented and rationale for changes included in commits. * When you need feedback or help, or you think the branch is ready for merging, open a pull request. * After someone else has reviewed and signed off on the changes, the @@ -78,11 +78,17 @@ remote, we'll call it ``upstream``:: Make your changes ''''''''''''''''' -* **Create a branch**: Note that you have only one ``pull request`` per branch:: +* **Create a branch**: Remember to branch off master/main. Note: you have only one ``pull request`` per branch:: git checkout -b DESCRIPTIVE_BRANCH_NAME -* **Hack away**: Make your changes, test and commit as you go. Remember please only address one issue per branch/pull request +* **Hack away**: Make your changes. Note: please only address one issue per branch/pull request. +* **Test**: Test as you go. +* **Commit**: Commit as you go, provide a biref descrption:: + + git add FILENAME.EXT + git commit -m "BRIEF DESCRIPTION" + * **Test**: Perform final testing. Push changes and submit a Pull Request @@ -119,4 +125,3 @@ until it is closed. .. _git-flow: http://nvie.com/posts/a-successful-git-branching-model .. _GitHub flow: http://scottchacon.com/2011/08/31/github-flow.html .. _GitHub account: https://github.com/signup - diff --git a/RST_DOC_STYLE.rst b/RST_DOC_STYLE.rst new file mode 100644 index 0000000..fa08751 --- /dev/null +++ b/RST_DOC_STYLE.rst @@ -0,0 +1,249 @@ +Recommended RST Document Style +============================== + +This document is basically a cheat sheet for reStructuredText to help guide new people in following TurnKeyLinux's documenting style in GitHub. + +Contents +-------- + +* `Headers <#Headers>`_ + +* `Horizontal Rules <#horizontal-rules>`_ + +* `Code Formatting <#code-formatting>`_ + +* `Basic Formatting <#basic-formatting>`_ + +* `Code Blocks <#code-blocks>`_ + +* `Escaping Markup <#escaping-markup>`_ + +* `Lists <#Lists>`_ + +* `Linking <#linking>`_ + +* `References <#references>`_ + +Headers +------- + +Typically ``Header 1`` is used for README.rst, any additional documentation pages will start with ``Header 2``, then ``Header 3`` for page sections and ``Header 4`` for subsections. ``Header 5`` is rarely used. + +The underlining *must* be as long as the header text. + +Example of headers:: + + ======== + Header 1 + ======== + + Header 2 + ======== + + Header 3 + -------- + + Header 3 with a longer text + --------------------------- + + Header 4 + ^^^^^^^^ + + Header 5 + """""""" + +Horizontal Rules +---------------- + +Simply place four or more hyphens (``-``) on there own line with blank lines before and after, with no indent + +For example: + +``----`` + +---- + +Code Formatting +--------------- + +To use ``highlighted monospaced text``, prepend and append the text with a double backquote (``````). + +For example:: + + Change into directory with ``cd /etc/`` and show a long list of of the directory with ``ls -l``. + +Change into directory with ``cd /etc/`` and show a long list of of the directory with ``ls -l``. + +Basic Formatting +---------------- + +``*italic text*`` + +*italic text* + +``**bold text**`` + +**bold text** + +Code Blocks +----------- + +Follow a sentence or paragraph with a double colon (``::``), then leave a blank line and indent the next line 1 tab or four spaces to create a monospaced highlighted block of text. + +For example:: + + the quick brown fox jumps over the lazy dog:: + + the quick brown fox jumps over the lazy dog + the quick brown fox jumps over the lazy dog + +the quick brown fox jumps over the lazy dog:: + + the quick brown fox jumps over the lazy dog + the quick brown fox jumps over the lazy dog + +Escaping Markup +--------------- + +Occassionally you will want to use markup characters just as them themselves and without being interpreted. Markup characters are not interpreted when used within double backquotes or within a code block. In other contexts, you can precede the markup character with a backslash (\\) to escape the interpretation. This also applies to the backslash itself. + +For example: + +``\*This\* is not *italic* and \**this\** is not **bold**.`` + +\*This\* is not *italic* and \**this\** is not **bold**. + +Lists +----- +Numbered +^^^^^^^^ + +Create a auto-enumerated list with hash and fullstop (``#.``) + +For example:: + + #. First item + #. Second item + #. Third item + + #. Frist sub item + #. Second sub item + #. Fourth item + +#. First item +#. Second item +#. Third item + + #. First sub item + #. Second sub item +#. Fourth item + +Create a numbered list with numbers and a fullstop (``1.``) always starting with ``1`` . + +For example:: + + 1. First item + 2. Second item + 3. Third item + + 1. First sub item + 2. Second sub item + 4. Fourth item + +1. First item +2. Second item +3. Third item + + 1. First sub item + 2. Second sub item +4. Fourth item + +Bullet +^^^^^^ + +Create a bullet point list with asterisk (``*``). + +For example:: + + * First item + * Second item + that continues on a second line + * Third item + + * Use nested lists + * By indenting 4-7 spaces + * Fourth item + +* First item +* Second item + that continues on a second line +* Third item + + * Use nested lists + * By indenting 4-7 spaces +* Fourth item + +Linking +------- + +Hyperlink URLs +^^^^^^^^^^^^^^ + +Hyperlinks can be created by prepending and appending with a single backqoute (`````) and including the reference or link at the end in angle brackets (``<>``) followed by the underscore (``_``). + +You can also create links that reference a list at the bottom of the page. Using double full stop and a space (``..``) will hide the reference text from being displayed. + +For example:: + + * `Issue Tracker`_ + * `Wiki`_ + * `Support Forum`_ + * `General Discussion Forum`_ + * `Guidelines and Walk Through`_ + + .. _Issue Tracker: https://github.com/turnkeylinux/tracker/issues/ + .. _Wiki: https://github.com/turnkeylinux/tracker/wiki/ + .. _Support Forum: http://www.turnkeylinux.org/forum/support/ + .. _General Discussion Forum: http://www.turnkeylinux.org/forum/general/ + .. _Guidelines and Walk Through: https://github.com/turnkeylinux/tracker/blob/master/GITFLOW.rst + +* `Issue Tracker`_ +* `Wiki`_ +* `Support Forum`_ +* `General Discussion Forum`_ +* `Guidelines and Walk Through`_ + +.. _Issue Tracker: https://github.com/turnkeylinux/tracker/issues/ +.. _Wiki: https://github.com/turnkeylinux/tracker/wiki/ +.. _Support Forum: http://www.turnkeylinux.org/forum/support/ +.. _General Discussion Forum: http://www.turnkeylinux.org/forum/general/ +.. _Guidelines and Walk Through: https://github.com/turnkeylinux/tracker/blob/master/GITFLOW.rst + +Link to Heading +^^^^^^^^^^^^^^^ + +Link to a heading in the same document. + +```Code Formatting <#code-formatting>`_`` + +`Code Formatting <#code-formatting>`_ + +Link to File +^^^^^^^^^^^^ + +Link to a file in the same repo. + +```Follow TurnKeyLinux Workflow using git and GitHub `_`` + +`Follow TurnKeyLinux Workflow using git and GitHub `_ + + + +References +---------- + +https://gist.github.com/dupuy/1855764 + +https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst + +https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html \ No newline at end of file