vyos/vyos-documentation
1
0
Fork 0
mirror of https://github.com/vyos/vyos-documentation.git synced 2025-10-26 08:41:46 +01:00
Code Issues Packages Projects Releases Wiki Activity

development: adjust headlines to new level syntax

Browse Source
This commit is contained in:
Christian Poessinger 2019-12-07 18:37:26 +01:00
parent d247468e03
commit 457420f0e7
1 changed files with 25 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
docs/contributing/development.rst
View File

@ -1,7 +1,8 @@
.. _development: .. _development:
###########
Development Development
=========== ###########
All VyOS source code is hosted on GitHub under the VyOS organization which can All VyOS source code is hosted on GitHub under the VyOS organization which can
be found here: https://github.com/vyos 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. 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 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 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: .. _prepare_commit:
Preparing patch/commit Prepare patch/commit
^^^^^^^^^^^^^^^^^^^^^^ --------------------
In a big system, such as VyOS, that is comprised of multiple components, it's 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 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 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 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 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 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: is located in the ``vyatta-webproxy`` package which can be found here:
https://github.com/vyos/vyatta-webproxy 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 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 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. * Submit the patch ``git push`` and create the GitHub pull-request.
Attach patch to Phabricator task Attach patch to Phabricator task
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ --------------------------------
Follow the above steps on how to "Fork repository to submit a Patch". Instead 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/ 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`` commits into its appropriate patch files: ``git format-patch -2``
Coding Guidelines Coding Guidelines
----------------- =================
Like any other project we have some small guidelines about our source code, too. 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 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. considerations for Python 2 compatibility **should** be taken at any time.
Formatting Formatting
^^^^^^^^^^ ----------
* Python: Tabs **shall not** be used. Every indentation level should be 4 spaces * 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 * 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. 2>/dev/null`` now you can call the linter using ``gg=G`` in command mode.
Text generation Text generation
############### ^^^^^^^^^^^^^^^
Template processor **should** be used for generating config files. Built-in Template processor **should** be used for generating config files. Built-in
string formatting **may** be used for simple line-oriented formats where every 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_. The default template processor for VyOS code is Jinja2_.
Summary Summary
####### -------
When modifying the source code, remember these rules of the legacy elimination When modifying the source code, remember these rules of the legacy elimination
campaign: campaign:
@ -215,7 +216,7 @@ campaign:
* No code incompatible with Python3 * No code incompatible with Python3
Python Python
------ ======
The switch to the Python programming language for new code is not merely a 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 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 modules or even rewrite a whole bunch of code in the new style XML/Pyhon
interface. interface.
Configuration script structure and behaviour Configuration Script Structure and Behaviour
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ --------------------------------------------
Your configuration script or operation mode script which is also written in 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 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 ``interfaces-bonding.py`` (for tag nodes) implementation. Both files can be
found in the vyos-1x_ repository. 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*. 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 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. editor can alleviate the issue with verbosity.
Example: Example:
^^^^^^^^
.. code-block:: xml .. 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. and so on is implemented in configuration scripts instead.
Guidelines Guidelines
^^^^^^^^^^ ----------
Use of numbers Use of numbers
############## ^^^^^^^^^^^^^^^
Use of numbers in command names **should** be avoided unless a number is a 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 part of a protocol name or similar. Thus, ``protocols ospfv3`` is perfectly
fine, but something like ``server-1`` is questionable at best. fine, but something like ``server-1`` is questionable at best.
Help String Help String
########### ^^^^^^^^^^^
To ensure uniform look and feel, and improve readability, we should follow a To ensure uniform look and feel, and improve readability, we should follow a
set of guidelines consistently. set of guidelines consistently.
@ -554,7 +554,7 @@ Examples:
* Bad: "Disables IPv6 forwarding" * Bad: "Disables IPv6 forwarding"
Migrating old CLI Migrating old CLI
^^^^^^^^^^^^^^^^^ -----------------
.. list-table:: .. list-table::
:widths: 25 25 50 :widths: 25 25 50
@ -618,7 +618,7 @@ Migrating old CLI
- All logic should be in the scripts - All logic should be in the scripts
Continous Integration Continous Integration
--------------------- =====================
VyOS makes use of Jenkins_ as our Continous Integration (CI) service. Our CI 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 server is publicly accessible here: https://ci.vyos.net. You can get a brief