diff options
Diffstat (limited to 'docs/contributing')
| -rw-r--r-- | docs/contributing/build-vyos.rst | 102 | ||||
| -rw-r--r-- | docs/contributing/development.rst | 6 | ||||
| -rw-r--r-- | docs/contributing/documentation.rst | 59 | ||||
| -rw-r--r-- | docs/contributing/issues-features.rst | 30 |
4 files changed, 169 insertions, 28 deletions
diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index bc113750..d158594e 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -121,6 +121,108 @@ Good luck! or ``rolling`` image. Make sure to choose the matching container for the version of VyOS that is being built. +.. _build_packages: + +Build packages +-------------- + +VyOS requires a bunch of packages which are VyOS specific and thus can not be +found in any Debian Upstream mirrror. Those packages can be found at the VyOS +GitHub project (https://github.com/vyos) and there is a nice helper script +available to build and list those individual packages. + +`scripts/build-packages` provides an easy interface to automate the process +of building all VyOS related packages that are not part of the upstream Debian +version. Execute it in the root of the `vyos-build` directory to start +compilation. + +.. code-block:: none + + $ scripts/build-packages -h + usage: build-packages [-h] [-c | -k | -f] [-v] [-l] [-b BUILD [BUILD ...]] + [-p] [--blacklist BLACKLIST [BLACKLIST ...]] + + optional arguments: + -h, --help show this help message and exit + -c, --clean Re-clone required Git repositories + -k, --keep Keep modified Git repositories + -f, --fetch Fetch sources only, no build + -v, --verbose Increase logging verbosity for each occurance + -l, --list-packages List all packages to build + -b BUILD [BUILD ...], --build BUILD [BUILD ...] + Whitespace separated list of packages to build + -p, --parallel Build on all CPUs + --blacklist BLACKLIST [BLACKLIST ...] + Do not build/report packages when calling --list + +Git repositoriers are automatically fetched and build on demand. If you want to +work offline you can fetch all source code first with the `-f` option. + +The easiest way to compile is with the above mentioned Docker +container, it includes all dependencies for compiling supported packages. + +.. code-block:: none + + $ docker run --rm -it -v $(pwd):/vyos -w /vyos \ + --sysctl net.ipv6.conf.lo.disable_ipv6=0 \ + vyos-builder scripts/build-packages + +.. note:: `--sysctl net.ipv6.conf.lo.disable_ipv6=0` is required to build the + `vyos-strongswan` package + +.. note:: Prior to executing this script you need to create or build the Docker + container and checkout all packages you want to compile. + +Building single package(s) +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To build a single package use the same script as above but specify packages with +`-b`: + +Executed from the root of `vyos-build` + +.. code-block:: none + + $ docker run --rm -it -v $(pwd):/vyos -w /vyos/packages/PACKAGENAME \ + --sysctl net.ipv6.conf.lo.disable_ipv6=0 \ + vyos-builder scripts/build-packages -b <package> + +.. note:: `--sysctl net.ipv6.conf.lo.disable_ipv6=0` is only needed when + building `vyos-strongswan` and can be ignored on other packages. + +.. note:: `vyos-strongswan` will only compile on a Linux system, running on + macOS or Windows might result in a unittest deadlock (it never exits). + +Building single packages from your own repositories +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can also build packages that are not from the default git repositories, +for example from your own forks of the official vyos repositories. + +First create a directory "packages" at the top level of the vyos-build +repository and clone your package into it (creating a subdirectory with the +package contents). Then checkout the correct branch or commit you want to build +before building the package. + +Example using `git@github.com:myname/vyos-1x.git` repository to build vyos-1x: + +.. code-block:: none + + $ mkdir packages + $ cd packages + $ git clone git@github.com:myname/vyos-1x.git + $ cd .. + $ docker run --rm -it -v $(pwd):/vyos -w /vyos/packages/PACKAGENAME \ + --sysctl net.ipv6.conf.lo.disable_ipv6=0 \ + vyos-builder scripts/build-packages -b vyos-1x + +.. note:: You need to git pull manually after you commit to the remote and + before rebuilding, the local repository won't be updated automatically. + +.. warning:: Any packages in the packages directory will be added to the iso + during build, replacing the upstream ones. Make sure you delete them (both + the source directories and built deb packages) if you want to build an iso + from purely upstream packages. .. _upstream_packages: diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index 1c257772..fed06e6f 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -486,7 +486,7 @@ 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 +implemented in :vytask:`T1843`. XML interface definitions tend to have a lot of duplicated code in areas such as: * VIF (incl. VIF-S/VIF-C) @@ -695,11 +695,11 @@ http://dev.packages.vyos.net/repositories/. .. _VyConf: https://github.com/vyos/vyconf/tree/master/data/schemata .. _vyos-1x: https://github.com/vyos/vyos-1x/tree/current/schema .. _Jinja2: https://jinja.palletsprojects.com/ -.. _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 + +.. include:: ../common-references.rst diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index 48cc063b..2d9f14d1 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -5,12 +5,12 @@ Documentation As most software projects we also have a lack in documentation. We encourage every VyOS user to help us improve our documentation. This will not only be -benefical four you (when reading something up) but also for the whole world. +beneficial for you (when reading something up) but also for the whole world. -If you are willing to contribute to our documentation this is the definate -guid how to do so. +If you are willing to contribute to our documentation this is the definite +guide how to do so. -.. note:: In contrast to submitting code patches there is no requirement that +.. note:: In contrast to submitting code patches, there is no requirement that you open up a Phabricator_ task prior to submitting a Pull-Request to the documentation. @@ -147,29 +147,60 @@ system numbers for the documentation: Please don't use other public address space. - Custom Sphinx-doc Markup ^^^^^^^^^^^^^^^^^^^^^^^^ -When documenting CLI commands use the ``.. cfgcmd::`` directive for all -configuration mode commands. When documenting operational level command use -the ``.. opcmd::`` directive. An explanation of the described command should -be added below this statement. +When writing the documentation custom commands have been developed. Please +make yourself comfortable with those commands as this eases the way we +render the documentation. -**Example** +cfgcmd +"""""" -.. code-block:: none +When documenting CLI commands use the ``.. cfgcmd::`` directive for all +configuration mode commands. An explanation of the described command should be +added below this statement. - .. opcmd:: show protocols static arp +With those custom commands it will be possible to render them in a more +descriptive way in the resulting HTML/PDF manual. - Display all known ARP table entries spanning accross all interfaces +.. code-block:: none .. cfgcmd:: set protocols static arp 192.0.2.100 hwaddr 00:53:27:de:23:aa This will configure a static ARP entry always resolving `192.0.2.100` to `00:53:27:de:23:aa`. +opcmd +""""" + +When documenting operational level command use the ``.. opcmd::`` directive. +An explanation of the described command should be added below this statement. + +With those custom commands it will be possible to render them in a more +descriptive way in the resulting HTML/PDF manual. + +.. code-block:: none + + .. opcmd:: show protocols static arp + + Display all known ARP table entries spanning across all interfaces + +vytask +"""""" + +When referencing to VyOS Phabricator Tasks, there is a custom Spinx Markup +command called ``vytask`` which automatically renders to a proper Phabricator +URL. This is heavily used in the :ref:`release-notes` section. + +.. code-block:: none + + * :vytask:`T1605` Fixed regression in L2TP/IPsec server + * :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly + + .. _Sphinx-doc: https://www.sphinx-doc.org .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html -.. _Phabricator: https://phabricator.vyos.net .. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md + +.. include:: ../common-references.rst diff --git a/docs/contributing/issues-features.rst b/docs/contributing/issues-features.rst index 3a1738d7..1c6563b9 100644 --- a/docs/contributing/issues-features.rst +++ b/docs/contributing/issues-features.rst @@ -1,10 +1,14 @@ .. _issues_features: +####################### Issues/Feature requests -======================= +####################### + +.. _bug_report: Bug Report/Issue ----------------- +================ + Issues or bugs are found in any software project. VyOS is not an exception. All issues should be reported to the developers. This lets the developers know @@ -12,7 +16,7 @@ what is not working properly. Without this sort of feedback every developer will believe that everything is working correctly. I have found a bug, what should I do? -************************************* +------------------------------------- When you believe you have found a bug, it is always a good idea to verify the issue prior to opening a bug request. @@ -22,7 +26,7 @@ issue prior to opening a bug request. * Get community support via Slack_ or our Forum_ Ensure the problem is reproducible -********************************** +---------------------------------- When you are able to verify that it is actually a bug, spend some time to document how to reproduce the issue. This documentation can be invaluable. @@ -38,7 +42,7 @@ information can be very useful. * What commands did you use? Use e.g. ``run show configuration commands`` Include output -************** +-------------- The output you get when you find a bug can provide lots of information. If you get an error message on the screen, copy it exactly. Having the exact message @@ -47,18 +51,21 @@ messages that also are from the time of the issue, include those. They may also contain information that is helpful for the development team. Report a Bug -************ +------------ -Create an account on VyOS Phabricator_. Phabricator_ is located at -https://phabricator.vyos.net. To create a bug-report use the quick link in the -left side under the specific project. +In order to open up a bug-report/feature request you need to create yourself +an account on VyOS Phabricator_. On the left side of the specific project (VyOS +1.2 or VyOS 1.3) you will find quick-links for opening a bug-report/feature +request. * Provide as much information as you can * Which version of VyOS are you using? ``run show version`` * How can we reproduce this Bug? +.. _feature_request: + Feature Request ---------------- +=============== You have an idea of how to make VyOS better or you are in need of a specific feature which all users of VyOS would benefit from? To send a feature request @@ -69,4 +76,5 @@ the left side under the specific project. .. _documentation: https://docs.vyos.io .. _Slack: https://slack.vyos.io .. _Forum: https://forum.vyos.io -.. _Phabricator: https://phabricator.vyos.net
\ No newline at end of file + +.. include:: ../common-references.rst
\ No newline at end of file |