diff options
Diffstat (limited to 'docs/contributing/development.rst')
| -rw-r--r-- | docs/contributing/development.rst | 85 |
1 files changed, 73 insertions, 12 deletions
diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index c699ad48..1c257772 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -41,14 +41,18 @@ impossible to keep track of all the changes and bugs/feature requests in one's head. We use a bugtracker known as Phabricator_ for it ("issue tracker" would be a better term, but this one stuck). -The information is used in two ways: +The information is used in three ways: * Keep track of the progress (what we've already done in this branch and what we still need to do). * Prepare release notes for upcoming releases -To make this approach work, every change must be associated with a bug number +* Help future maintainers of VyOS (it could be you!) to find out why certain + things have been changed in the codebase or why certain features have been + added + +To make this approach work, every change must be associated with a task number (prefixed with **T**) and a component. If there is no bug report/feature request for the changes you are going to make, you have to create a Phabricator_ task first. Once there is an entry in Phabricator_, you should reference its id in @@ -61,19 +65,21 @@ If there is no Phabricator_ reference in the commits of your pull request, we have to ask you to ammend the commit message. Otherwise we will have to reject it. -In general, use an editor to create your commit messages rather than passing -them on the command line. The format should be and is inspired by this blog -post: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html +Writing good commit messages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* A single, short, summary of the commit (recommended 50 characters or less, - not exceeding 80 characters) +The format should be and is inspired by: https://git-scm.com/book/ch5-2.html - * Add prefix of changed component to your commit headline, e.g. ``snmp: - T1111:`` or ``ethernet: T2222:``. If multiple components are touched by - this commit, you can use multiple prefixes, e.g.: ``snmp: ethernet:`` +* A single, short, summary of the commit (recommended 50 characters or less, + not exceeding 80 characters) containing a prefix of the changed component + and the corresponding Phabricator_ reference e.g. ``snmp: T1111:`` or + ``ethernet: T2222:`` - multiple components could be concatenated as in + ``snmp: ethernet: T3333`` -* Followed by a blank line (this line is mandatory - else Git will treat the - whole commit message as the headline only) +* In some contexts, the first line is treated as the subject of an email and + the rest of the text as the body. The blank line separating the summary from + the body is critical (unless you omit the body entirely); tools like rebase + can get confused if you run the two together. * Followed by a message which describes all the details like: @@ -108,6 +114,7 @@ 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 + Determinine source package -------------------------- @@ -125,6 +132,7 @@ 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 and submit Patch -------------------------------- @@ -161,6 +169,7 @@ record them in your created Git commit: * Submit the patch ``git push`` and create the GitHub pull-request. + Attach patch to Phabricator task -------------------------------- @@ -172,6 +181,7 @@ commits and send it to maintainers@vyos.net or attach it directly to the bug * Export last commit to patch file: ``git format-patch`` or export the last two commits into its appropriate patch files: ``git format-patch -2`` + Coding Guidelines ================= @@ -184,6 +194,7 @@ implied logic of any one source file.. 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 ---------- @@ -195,6 +206,7 @@ Formatting ``au FileType xml setlocal equalprg=xmllint\ --format\ --recover\ -\ 2>/dev/null`` now you can call the linter using ``gg=G`` in command mode. + Text generation ^^^^^^^^^^^^^^^ @@ -205,6 +217,7 @@ used for structured, multi-line formats such as those used by ISC DHCPd. The default template processor for VyOS code is Jinja2_. + Summary ------- @@ -215,6 +228,7 @@ campaign: * No old style command definitions * No code incompatible with Python3 + Python ====== @@ -240,6 +254,7 @@ 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 -------------------------------------------- @@ -361,6 +376,7 @@ 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 (used for CLI definitions) ============================== @@ -466,6 +482,46 @@ Command definitions are purely declarative, and cannot contain any logic. All logic for generating config files for target applications, restarting services and so on is implemented in configuration scripts instead. +GNU Preprocessor +---------------- + +XML interface definition files use the `xml.in` file extension which was +implemented in T1843_. XML interface definitions tend to have a lot of +duplicated code in areas such as: + +* VIF (incl. VIF-S/VIF-C) +* Address +* Description +* Enabled/Disabled + +Instead of supplying all those XML nodes multiple times there are now include +files with predefined features. Brief overview: + +* `IPv4, IPv6 and DHCP(v6)`_ address assignment +* `IPv4, IPv6`_ address assignment +* `VLAN (VIF)`_ definition +* `MAC address`_ assignment + +All interface definition XML input files (.in suffix) will be sent to the GCC +preprocess and the output is stored in the `build/interface-definitions` +folder. The previously mentioned `scripts/build-command-templates` script +operates on the `build/interface-definitions` folder to generate all required +CLI nodes. + +.. code-block:: none + + $ make interface_definitions + install -d -m 0755 build/interface-definitions + install -d -m 0755 build/op-mode-definitions + Generating build/interface-definitions/intel_qat.xml from interface-definitions/intel_qat.xml.in + Generating build/interface-definitions/interfaces-bonding.xml from interface-definitions/interfaces-bonding.xml.in + Generating build/interface-definitions/cron.xml from interface-definitions/cron.xml.in + Generating build/interface-definitions/pppoe-server.xml from interface-definitions/pppoe-server.xml.in + Generating build/interface-definitions/mdns-repeater.xml from interface-definitions/mdns-repeater.xml.in + Generating build/interface-definitions/tftp-server.xml from interface-definitions/tftp-server.xml.in + [...] + + Guidelines ---------- @@ -642,3 +698,8 @@ http://dev.packages.vyos.net/repositories/. .. _Phabricator: https://phabricator.vyos.net/ .. _Jenkins: https://jenkins.io/ .. _Dockerhub: https://hub.docker.com/u/vyos/ +.. _T1843: https://phabricator.vyos.net/T1843 +.. _`IPv4, IPv6 and DHCP(v6)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/address-ipv4-ipv6-dhcp.xml.i +.. _`IPv4, IPv6`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/address-ipv4-ipv6.xml.i +.. _`VLAN (VIF)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/vif.xml.i +.. _`MAC address`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/interface-mac.xml.i |