Merge branch 'master' into newdirectives

4 files changed, 125 insertions, 15 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 29b33cdd..8102e9a9 100644
--- a/docs/contributing/documentation.rst
+++ b/docs/contributing/documentation.rst
@@ -215,4 +215,4 @@ URL. This is heavily used in the :ref:`release-notes` section.
 .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
 .. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md
 
-.. include:: ../common-references.rst
\ No newline at end of file
+.. 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