summaryrefslogtreecommitdiff
path: root/docs/contributing/development.rst
diff options
context:
space:
mode:
authorChristian Poessinger <christian@poessinger.com>2019-12-07 18:37:26 +0100
committerChristian Poessinger <christian@poessinger.com>2019-12-07 18:37:26 +0100
commit457420f0e7ccce12fa5642ac689bc15c7bee3654 (patch)
treedf7bcf03c520135f9f5631f07bd3884553e2ae1f /docs/contributing/development.rst
parentd247468e0379d70e26e30dc26bdfe13da8e62939 (diff)
downloadvyos-documentation-457420f0e7ccce12fa5642ac689bc15c7bee3654.tar.gz
vyos-documentation-457420f0e7ccce12fa5642ac689bc15c7bee3654.zip
development: adjust headlines to new level syntax
Diffstat (limited to 'docs/contributing/development.rst')
-rw-r--r--docs/contributing/development.rst50
1 files changed, 25 insertions, 25 deletions
diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst
index f1461480..8558284a 100644
--- a/docs/contributing/development.rst
+++ b/docs/contributing/development.rst
@@ -1,7 +1,8 @@
.. _development:
+###########
Development
-===========
+###########
All VyOS source code is hosted on GitHub under the VyOS organization which can
be found here: https://github.com/vyos
@@ -20,8 +21,8 @@ https://github.com/vyos/vyos-build
The README.md file will guide you to use the this top level repository.
-Submit a patch
---------------
+Submit a Patch
+==============
Patches are always more then welcome. To have a clean and easy to maintain
repository we have some guidelines when working with Git. A clean repository
@@ -32,8 +33,8 @@ file(s) history by invoking ``git log path/to/file.txt``.
.. _prepare_commit:
-Preparing patch/commit
-^^^^^^^^^^^^^^^^^^^^^^
+Prepare patch/commit
+--------------------
In a big system, such as VyOS, that is comprised of multiple components, it's
impossible to keep track of all the changes and bugs/feature requests in one's
@@ -107,8 +108,8 @@ Limits:
Please submit your patches using the well-known GitHub pull-request against our
repositories found in the VyOS GitHub organisation at https://github.com/vyos
-Determining package for a fix
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Determinine source package
+--------------------------
Suppose you want to make a change in the webproxy script but yet you do not know
which of the many VyOS packages ship this file. You can determine the VyOS
@@ -124,8 +125,8 @@ This means the file in question (``/opt/vyatta/sbin/vyatta-update-webproxy.pl``)
is located in the ``vyatta-webproxy`` package which can be found here:
https://github.com/vyos/vyatta-webproxy
-Fork repository to submit a Patch
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Fork Repository and submit Patch
+--------------------------------
Forking the repository and submitting a GitHub pull-request is the preferred
way of submitting your changes to VyOS. You can fork any VyOS repository to your
@@ -161,7 +162,7 @@ record them in your created Git commit:
* Submit the patch ``git push`` and create the GitHub pull-request.
Attach patch to Phabricator task
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------------
Follow the above steps on how to "Fork repository to submit a Patch". Instead
of uploading "pushing" your changes to GitHub you can export the patches/
@@ -172,7 +173,7 @@ commits and send it to maintainers@vyos.net or attach it directly to the bug
commits into its appropriate patch files: ``git format-patch -2``
Coding Guidelines
------------------
+=================
Like any other project we have some small guidelines about our source code, too.
The rules we have are not there to punish you - the rules are in place to help
@@ -184,7 +185,7 @@ Python 3 **shall** be used. How long can we keep Python 2 alive anyway? No
considerations for Python 2 compatibility **should** be taken at any time.
Formatting
-^^^^^^^^^^
+----------
* Python: Tabs **shall not** be used. Every indentation level should be 4 spaces
* XML: Tabs **shall not** be used. Every indentation level should be 2 spaces
@@ -195,7 +196,7 @@ Formatting
2>/dev/null`` now you can call the linter using ``gg=G`` in command mode.
Text generation
-###############
+^^^^^^^^^^^^^^^
Template processor **should** be used for generating config files. Built-in
string formatting **may** be used for simple line-oriented formats where every
@@ -205,7 +206,7 @@ used for structured, multi-line formats such as those used by ISC DHCPd.
The default template processor for VyOS code is Jinja2_.
Summary
-#######
+-------
When modifying the source code, remember these rules of the legacy elimination
campaign:
@@ -215,7 +216,7 @@ campaign:
* No code incompatible with Python3
Python
-------
+======
The switch to the Python programming language for new code is not merely a
change of the language, but a chance to rethink and improve the programming
@@ -239,8 +240,8 @@ Please use the following template as good starting point when developing new
modules or even rewrite a whole bunch of code in the new style XML/Pyhon
interface.
-Configuration script structure and behaviour
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Configuration Script Structure and Behaviour
+--------------------------------------------
Your configuration script or operation mode script which is also written in
Python3 should have a line break on 80 characters. This seems to be a bit odd
@@ -360,8 +361,8 @@ For easy orientation we suggest you take a look on the ``ntp.py`` or
``interfaces-bonding.py`` (for tag nodes) implementation. Both files can be
found in the vyos-1x_ repository.
-XML - CLI
----------
+XML (used for CLI definitions)
+==============================
The bash (or better vbash) completion in VyOS is defined in *templates*.
Templates are text files (called ``node.def``) stored in a directory tree. The
@@ -384,7 +385,6 @@ there is no other format now that would allow this. Besides, a specialized XML
editor can alleviate the issue with verbosity.
Example:
-^^^^^^^^
.. code-block:: xml
@@ -467,17 +467,17 @@ logic for generating config files for target applications, restarting services
and so on is implemented in configuration scripts instead.
Guidelines
-^^^^^^^^^^
+----------
Use of numbers
-##############
+^^^^^^^^^^^^^^^
Use of numbers in command names **should** be avoided unless a number is a
part of a protocol name or similar. Thus, ``protocols ospfv3`` is perfectly
fine, but something like ``server-1`` is questionable at best.
Help String
-###########
+^^^^^^^^^^^
To ensure uniform look and feel, and improve readability, we should follow a
set of guidelines consistently.
@@ -554,7 +554,7 @@ Examples:
* Bad: "Disables IPv6 forwarding"
Migrating old CLI
-^^^^^^^^^^^^^^^^^
+-----------------
.. list-table::
:widths: 25 25 50
@@ -618,7 +618,7 @@ Migrating old CLI
- All logic should be in the scripts
Continous Integration
----------------------
+=====================
VyOS makes use of Jenkins_ as our Continous Integration (CI) service. Our CI
server is publicly accessible here: https://ci.vyos.net. You can get a brief