From 628c874320a27182add319cd7ed71460e8a5cd7d Mon Sep 17 00:00:00 2001 From: Jeremy Davis Date: Mon, 13 Nov 2017 11:27:27 +1100 Subject: [PATCH 01/19] Update CONTRIBUTING.md --- CONTRIBUTING.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c2dbd9e..fc30346 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,14 +26,14 @@ 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) @@ -45,7 +45,7 @@ Development of TKL is loosely based on [GitHub Flow](http://scottchacon.com/2011 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. @@ -83,7 +83,7 @@ Now that you're finished and all changes are committed, you need to push them to 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. -###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). From 4d5a3a50ffd0e7ced5658e60985ca842e5b83a97 Mon Sep 17 00:00:00 2001 From: Jeremy Davis Date: Tue, 9 Nov 2021 15:08:00 +1100 Subject: [PATCH 02/19] Commit initial placeholder codestyle doc. --- CODESTYLE.rst | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 CODESTYLE.rst 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 From a6ff611a216442d6313cdf3084f3d27db5f157d3 Mon Sep 17 00:00:00 2001 From: badco Date: Wed, 12 Jan 2022 22:15:19 +1300 Subject: [PATCH 03/19] Added new RST doc --- RST_DOC_STYLE.rst | 196 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 RST_DOC_STYLE.rst diff --git a/RST_DOC_STYLE.rst b/RST_DOC_STYLE.rst new file mode 100644 index 0000000..a631560 --- /dev/null +++ b/RST_DOC_STYLE.rst @@ -0,0 +1,196 @@ +Recommended RST Document Style +============================== + +This document is basically a cheat sheet for reStructuredText to help guide new people in following TurnKeyLinux's documenting style. + +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>`_ + +* `Hyperlink URLs <#hyperlink-urls>`_ + +* `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 needs to be atleast as long as the text + +Example of headers:: + + ======== + Header 1 + ======== + + Header 2 + ======== + + Header 3 + -------- + + Header 3 with a longer text + --------------------------- + + Header 4 + ^^^^^^^^ + + Header 5 + """""""" + +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 (``::``) 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 numbered list with ``#``. + +For example:: + + #. First item + #. Second item + #. Third item + #. Frist sub item + #. Second sub item + #. Fourth item + +#. First item +#. Second item +#. Third item + #. Frist sub item + #. Second sub item +#. Fourth item + +Bullet +^^^^^^ + +Create a bullet point list with ``*``. + +For example:: + + * First item + * Second item + that continues on a second line + * Third item + * Use nested lists + * By indenting two 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 + +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 + +You can 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 \ No newline at end of file From feb698d20dc281fd479a400783c91b46269699f5 Mon Sep 17 00:00:00 2001 From: badco Date: Wed, 12 Jan 2022 22:27:22 +1300 Subject: [PATCH 04/19] Added horizontal rules and minor fixes --- RST_DOC_STYLE.rst | 33 +++++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/RST_DOC_STYLE.rst b/RST_DOC_STYLE.rst index a631560..5c75427 100644 --- a/RST_DOC_STYLE.rst +++ b/RST_DOC_STYLE.rst @@ -52,6 +52,15 @@ Example of headers:: Header 5 """""""" +Horizontal Rules +---------------- + +Simply place four or more hyphens (``-``) on there own line with blank lines before and after, with no indent + +``----`` + +---- + Code Formatting --------------- @@ -107,7 +116,7 @@ Lists Numbered ^^^^^^^^ -Create a numbered list with ``#``. +Create a numbered list with hash (``#``). For example:: @@ -128,7 +137,7 @@ For example:: Bullet ^^^^^^ -Create a bullet point list with ``*``. +Create a bullet point list with asterix (``*``). For example:: @@ -148,8 +157,11 @@ For example:: * 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 (``_``). @@ -181,7 +193,19 @@ For example:: .. _general discussion forum: http://www.turnkeylinux.org/forum/general/ .. _guidelines and walk through: https://github.com/turnkeylinux/tracker/blob/master/GITFLOW.rst -You can link to a file in the same repo. +Link to Heading +^^^^^^^^^^^^^^^ + +Link to a heading in the same document. + +```Headers <#Headers>`_`` + +`Headers <#Headers>`_ + +Link to File +^^^^^^^^^^^^ + +Link to a file in the same repo. ```Follow TurnKeyLinux Workflow using git and GitHub `_`` @@ -193,4 +217,5 @@ References ---------- https://gist.github.com/dupuy/1855764 + https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst \ No newline at end of file From e7783982a556f6d8ef8f3fdd6ef3e7b36a5e01ee Mon Sep 17 00:00:00 2001 From: badco Date: Wed, 12 Jan 2022 22:42:14 +1300 Subject: [PATCH 05/19] Fixing indented lists --- RST_DOC_STYLE.rst | 34 +++++++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/RST_DOC_STYLE.rst b/RST_DOC_STYLE.rst index 5c75427..58038e0 100644 --- a/RST_DOC_STYLE.rst +++ b/RST_DOC_STYLE.rst @@ -64,7 +64,7 @@ Simply place four or more hyphens (``-``) on there own line with blank lines bef Code Formatting --------------- -To use ``highlighted monospaced text``, prepend and append the text with a double backquote (``). +To use ``highlighted monospaced text``, prepend and append the text with a double backquote (``````). For example: @@ -116,22 +116,28 @@ Lists Numbered ^^^^^^^^ -Create a numbered list with hash (``#``). +Create a numbered 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 + #. Frist sub item #. Second sub item + #. Fourth item Bullet @@ -142,19 +148,29 @@ Create a bullet point list with asterix (``*``). For example:: * First item + * Second item + that continues on a second line + * Third item + * Use nested lists - * By indenting two spaces + * 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 @@ -177,9 +193,9 @@ For example:: .. _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 + .. _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`_ @@ -189,9 +205,9 @@ For example:: .. _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 +.. _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 ^^^^^^^^^^^^^^^ From 8352e9373903c898e42009d8817e868e41aec74c Mon Sep 17 00:00:00 2001 From: badco Date: Wed, 12 Jan 2022 22:43:24 +1300 Subject: [PATCH 06/19] Fixing indented lists --- RST_DOC_STYLE.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/RST_DOC_STYLE.rst b/RST_DOC_STYLE.rst index 58038e0..68b9a49 100644 --- a/RST_DOC_STYLE.rst +++ b/RST_DOC_STYLE.rst @@ -127,15 +127,19 @@ For example:: #. Third item #. Frist sub item + #. Second sub item #. Fourth item #. First item + #. Second item + #. Third item #. Frist sub item + #. Second sub item #. Fourth item @@ -148,16 +152,16 @@ Create a bullet point list with asterix (``*``). 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 @@ -170,7 +174,7 @@ For example:: * Use nested lists * By indenting 4-7 spaces - + * Fourth item Linking From 3c48f15a9289bb80bfeba1a92569413e7c68be22 Mon Sep 17 00:00:00 2001 From: badco Date: Wed, 12 Jan 2022 22:52:55 +1300 Subject: [PATCH 07/19] Fixing indented lists --- RST_DOC_STYLE.rst | 34 +++++++--------------------------- 1 file changed, 7 insertions(+), 27 deletions(-) diff --git a/RST_DOC_STYLE.rst b/RST_DOC_STYLE.rst index 68b9a49..95fa265 100644 --- a/RST_DOC_STYLE.rst +++ b/RST_DOC_STYLE.rst @@ -20,7 +20,7 @@ Contents * `Lists <#Lists>`_ -* `Hyperlink URLs <#hyperlink-urls>`_ +* `Linking <#linking>`_ * `References <#references>`_ @@ -121,27 +121,17 @@ Create a numbered 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 - #. Frist sub item - #. Second sub item - #. Fourth item Bullet @@ -152,30 +142,20 @@ Create a bullet point list with asterix (``*``). 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 - +* First item +* Second item + that continues on a second line +* Third item * Use nested lists - * By indenting 4-7 spaces - -* Fourth item + * By indenting 4-7 spaces +* Fourth item Linking ------- From dcc3215f9293d0aeddca26d665949c90562a9b12 Mon Sep 17 00:00:00 2001 From: badco Date: Wed, 12 Jan 2022 22:55:00 +1300 Subject: [PATCH 08/19] Fixing indented lists --- RST_DOC_STYLE.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/RST_DOC_STYLE.rst b/RST_DOC_STYLE.rst index 95fa265..ad18c07 100644 --- a/RST_DOC_STYLE.rst +++ b/RST_DOC_STYLE.rst @@ -153,8 +153,8 @@ For example:: * Second item that continues on a second line * Third item - * Use nested lists - * By indenting 4-7 spaces + * Use nested lists + * By indenting 4-7 spaces * Fourth item Linking From 9d72e7220a1a7ebe5d2d24344c621fa4fb135089 Mon Sep 17 00:00:00 2001 From: badco Date: Wed, 12 Jan 2022 23:02:36 +1300 Subject: [PATCH 09/19] Fixing indented lists --- RST_DOC_STYLE.rst | 49 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 35 insertions(+), 14 deletions(-) diff --git a/RST_DOC_STYLE.rst b/RST_DOC_STYLE.rst index ad18c07..d856aec 100644 --- a/RST_DOC_STYLE.rst +++ b/RST_DOC_STYLE.rst @@ -116,24 +116,44 @@ Lists Numbered ^^^^^^^^ -Create a numbered list with hash and fullstop (``#.``) +Create a auto-enumerated list with hash and fullstop (``#.``) For example:: #. First item #. Second item #. Third item - #. Frist sub item - #. Second sub item + #. Frist sub item + #. Second sub item #. Fourth item #. First item #. Second item #. Third item - #. Frist sub item - #. Second sub item + + #. Frist sub item + #. Second sub item #. Fourth item +Create a auto-enumerated list with hash and fullstop (``#.``) + +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 ^^^^^^ @@ -145,17 +165,18 @@ For example:: * Second item that continues on a second line * Third item - * Use nested lists - * By indenting 4-7 spaces + * 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 +* First item +* Second item + that continues on a second line +* Third item + + * Use nested lists + * By indenting 4-7 spaces +* Fourth item Linking ------- From 7ab018963ba68b062168de3be56b68cfd0fe3de1 Mon Sep 17 00:00:00 2001 From: badco Date: Wed, 12 Jan 2022 23:10:25 +1300 Subject: [PATCH 10/19] Fixing indented lists --- RST_DOC_STYLE.rst | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/RST_DOC_STYLE.rst b/RST_DOC_STYLE.rst index d856aec..6df0d4f 100644 --- a/RST_DOC_STYLE.rst +++ b/RST_DOC_STYLE.rst @@ -29,7 +29,7 @@ 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 needs to be atleast as long as the text +The underlining needs to be atleast as long as the text. Example of headers:: @@ -57,6 +57,8 @@ Horizontal Rules Simply place four or more hyphens (``-``) on there own line with blank lines before and after, with no indent +For example: + ``----`` ---- @@ -68,7 +70,7 @@ To use ``highlighted monospaced text``, prepend and append the text with a doubl 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\``.`` Change into directory with ``cd /etc/`` and show a long list of of the directory with ``ls -l``. @@ -86,7 +88,7 @@ Basic Formatting Code Blocks ----------- -Follow a sentence or paragraph with a double colon (``::``) and indent the next line 1 tab or four spaces to create a monospaced highlighted block of text. +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:: @@ -123,6 +125,7 @@ For example:: #. First item #. Second item #. Third item + #. Frist sub item #. Second sub item #. Fourth item @@ -131,17 +134,18 @@ For example:: #. Second item #. Third item - #. Frist sub item + #. First sub item #. Second sub item #. Fourth item -Create a auto-enumerated list with hash and fullstop (``#.``) +Create a numbered list with hash and fullstop (``#.``) For example:: 1. First item 2. Second item 3. Third item + 1. First sub item 2. Second sub item 4. Fourth item @@ -165,6 +169,7 @@ For example:: * Second item that continues on a second line * Third item + * Use nested lists * By indenting 4-7 spaces * Fourth item @@ -219,7 +224,7 @@ Link to Heading Link to a heading in the same document. -```Headers <#Headers>`_`` +```Code Formatting <#code-formatting>`_`` `Headers <#Headers>`_ From bc8f291cfc60ab5ee7fab10f568e52ca20db0e85 Mon Sep 17 00:00:00 2001 From: badco Date: Thu, 13 Jan 2022 22:23:12 +1300 Subject: [PATCH 11/19] Fixing indented lists --- RST_DOC_STYLE.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/RST_DOC_STYLE.rst b/RST_DOC_STYLE.rst index 6df0d4f..d503ff7 100644 --- a/RST_DOC_STYLE.rst +++ b/RST_DOC_STYLE.rst @@ -1,7 +1,7 @@ Recommended RST Document Style ============================== -This document is basically a cheat sheet for reStructuredText to help guide new people in following TurnKeyLinux's documenting style. +This document is basically a cheat sheet for reStructuredText to help guide new people in following TurnKeyLinux's documenting style in GitHub. Contents -------- @@ -29,7 +29,7 @@ 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 needs to be atleast as long as the text. +The underlining *must* be as long as the header text. Example of headers:: @@ -68,9 +68,9 @@ Code Formatting To use ``highlighted monospaced text``, prepend and append the text with a double backquote (``````). -For example: +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\``. Change into directory with ``cd /etc/`` and show a long list of of the directory with ``ls -l``. @@ -161,7 +161,7 @@ For example:: Bullet ^^^^^^ -Create a bullet point list with asterix (``*``). +Create a bullet point list with asterisk (``*``). For example:: @@ -217,7 +217,7 @@ For example:: .. _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 +_Guidelines and Walk Through: https://github.com/turnkeylinux/tracker/blob/master/GITFLOW.rst Link to Heading ^^^^^^^^^^^^^^^ @@ -226,7 +226,7 @@ Link to a heading in the same document. ```Code Formatting <#code-formatting>`_`` -`Headers <#Headers>`_ +`Code Formatting <#code-formatting>`_ Link to File ^^^^^^^^^^^^ From 004baec0902fe49ccc620e2a6db0881f871a346e Mon Sep 17 00:00:00 2001 From: badco Date: Thu, 13 Jan 2022 22:23:54 +1300 Subject: [PATCH 12/19] Ammendments from feedback --- RST_DOC_STYLE.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RST_DOC_STYLE.rst b/RST_DOC_STYLE.rst index d503ff7..08d3fa5 100644 --- a/RST_DOC_STYLE.rst +++ b/RST_DOC_STYLE.rst @@ -217,7 +217,7 @@ For example:: .. _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 +.. _Guidelines and Walk Through: https://github.com/turnkeylinux/tracker/blob/master/GITFLOW.rst Link to Heading ^^^^^^^^^^^^^^^ From 49084a6e3df6649cb0c741be5195d741caa92c96 Mon Sep 17 00:00:00 2001 From: badco Date: Thu, 13 Jan 2022 22:25:59 +1300 Subject: [PATCH 13/19] Fixed Code Formatting example --- RST_DOC_STYLE.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RST_DOC_STYLE.rst b/RST_DOC_STYLE.rst index 08d3fa5..e52d12b 100644 --- a/RST_DOC_STYLE.rst +++ b/RST_DOC_STYLE.rst @@ -70,7 +70,7 @@ To use ``highlighted monospaced text``, prepend and append the text with a doubl 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``. Change into directory with ``cd /etc/`` and show a long list of of the directory with ``ls -l``. From 62e1c142e839a7d2115705ef0df5add7c6ad1f7f Mon Sep 17 00:00:00 2001 From: badco Date: Thu, 13 Jan 2022 22:28:54 +1300 Subject: [PATCH 14/19] Fixed numbered list text --- RST_DOC_STYLE.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RST_DOC_STYLE.rst b/RST_DOC_STYLE.rst index e52d12b..dfed4b0 100644 --- a/RST_DOC_STYLE.rst +++ b/RST_DOC_STYLE.rst @@ -138,7 +138,7 @@ For example:: #. Second sub item #. Fourth item -Create a numbered list with hash and fullstop (``#.``) +Create a numbered list starting with numbers and a fullstop (``#.``) For example:: From d65d7dd8b462da960b29ce5e30b7f3b03a51d538 Mon Sep 17 00:00:00 2001 From: badco Date: Thu, 13 Jan 2022 22:32:42 +1300 Subject: [PATCH 15/19] Fixed numbered list text --- RST_DOC_STYLE.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RST_DOC_STYLE.rst b/RST_DOC_STYLE.rst index dfed4b0..e121cca 100644 --- a/RST_DOC_STYLE.rst +++ b/RST_DOC_STYLE.rst @@ -138,7 +138,7 @@ For example:: #. Second sub item #. Fourth item -Create a numbered list starting with numbers and a fullstop (``#.``) +Create a numbered list with numbers and a fullstop (``1.``) always starting with ``1`` . For example:: From f7cab926ef5e3d727339ceab8089498711ca4534 Mon Sep 17 00:00:00 2001 From: badco Date: Thu, 13 Jan 2022 23:21:46 +1300 Subject: [PATCH 16/19] added a couple more git commands --- GITFLOW.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/GITFLOW.rst b/GITFLOW.rst index a7bf187..4610cd7 100644 --- a/GITFLOW.rst +++ b/GITFLOW.rst @@ -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 that 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, remember 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 From 5a0d10180b52934369c62920f99bf638b7382f8a Mon Sep 17 00:00:00 2001 From: badco Date: Thu, 13 Jan 2022 23:23:56 +1300 Subject: [PATCH 17/19] added a couple more git commands --- GITFLOW.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/GITFLOW.rst b/GITFLOW.rst index 4610cd7..34b8b1f 100644 --- a/GITFLOW.rst +++ b/GITFLOW.rst @@ -78,11 +78,11 @@ remote, we'll call it ``upstream``:: Make your changes ''''''''''''''''' -* **Create a branch**: Remember to branch off master/main. 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, 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:: From 5b181faec715755b25b75075242720931984ad1e Mon Sep 17 00:00:00 2001 From: badco Date: Thu, 13 Jan 2022 23:31:47 +1300 Subject: [PATCH 18/19] added additional reference --- RST_DOC_STYLE.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/RST_DOC_STYLE.rst b/RST_DOC_STYLE.rst index e121cca..fa08751 100644 --- a/RST_DOC_STYLE.rst +++ b/RST_DOC_STYLE.rst @@ -244,4 +244,6 @@ References https://gist.github.com/dupuy/1855764 -https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst \ No newline at end of file +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 From 437d148f042dbda623af32b312d30b18df9097fd Mon Sep 17 00:00:00 2001 From: Oleh Dmytrychenko Date: Sun, 6 Nov 2022 16:08:34 +0200 Subject: [PATCH 19/19] Documentation housekeeping. Improved punctuation consistency. Fixed typo. Clarified PR section. --- CONTRIBUTING.md | 36 ++++++++++++++++++------------------ GITFLOW.rst | 3 +-- 2 files changed, 19 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fc30346..a332345 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,27 +35,27 @@ Developers with good ideas are encouraged to be bold and contribute code. ### 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 **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 -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 34b8b1f..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 @@ -125,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 -