Proofread upstream-packages.rst

Author: teslazonda

docs/contributing/upstream-packages.rst

@@ -1,86 +1,88 @@
+:lastproofread: 2025-11-30
+
 .. _upstream_packages:
 
-Upstream packages
------------------
+#################
+Upstream Packages
+#################
 
-Many base system packages are pulled straight from Debian's main and contrib
-repositories, but there are exceptions.
+Many base system packages are pulled straight from Debian's ``main`` and
+``contrib`` repositories, but there are exceptions.
 
-This chapter lists those exceptions and gives you a brief overview what we
-have done on those packages. If you only want to build yourself a fresh ISO
-you can completely skip this chapter. It may become interesting once you have
-a VyOS deep dive.
+This page lists those exceptions and briefly describes changes made to
+these packages. If you only want to build a fresh ISO image, you can skip
+this section. This information may be useful for a deeper dive into VyOS.
 
-vyos-netplug
-^^^^^^^^^^^^
+``vyos-netplug``
+----------------
 
-Due to issues in the upstream version that sometimes set interfaces down, a
-modified version is used.
+VyOS uses a modified version because the upstream release sometimes causes
+network interfaces to go down.
 
-The source is located at https://github.com/vyos/vyos-netplug
+Source: https://github.com/vyos/vyos-netplug.
 
-In the future, we may switch to using systemd infrastructure instead. Building
-it doesn't require a special procedure.
+VyOS may switch to ``systemd`` in the future. Building the package does not
+require a special procedure.
 
-keepalived
-^^^^^^^^^^
+``keepalived``
+--------------
 
-Keepalived normally isn't updated to newer feature releases between Debian
-versions, so we are building it from source.
+``keepalived`` is not updated to newer feature releases between Debian releases.
+VyoS builds it from source.
 
-Debian does keep their package in git, but it's upstream tarball imported into
-git without its original commit history. To be able to merge new tags in, we
-keep a fork of the upstream repository with packaging files imported from
-Debian at https://github.com/vyos/keepalived-upstream
+Debian maintains the package in git, but the upstream tarball was imported
+without its original commit history. To allow merging new tags, we maintain
+a fork with packaging files imported from Debian: https://github.com/vyos/keepalived-upstream.
 
-strongswan
-^^^^^^^^^^
+``strongswan``
+--------------
 
-Our StrongSWAN build differs from the upstream:
+VyOS's StrongSWAN build differs from upstream:
 
-- strongswan-nm package build is disabled since we don't use NetworkManager
-- Patches for DMVPN are merged in
+- We disable the ``strongswan-nm`` package build because VyOS does not use
+  NetworkManager.
+- We merged patches for DMVPN.
 
-The source is at https://github.com/vyos/vyos-strongswan
+Source: https://github.com/vyos/vyos-strongswan
 
-DMVPN patches are added by this commit:
+DMVPN patches were added in this commit:
 https://github.com/vyos/vyos-strongswan/commit/1cf12b0f2f921bfc51affa3b81226
 
-Our op mode scripts use the python-vici module, which is not included in
-Debian's build, and isn't quite easy to integrate in that build. For this
-reason we debianize that module by hand now, using this procedure:
+VyOS's op-mode scripts use the ``python-vici`` module, which is not included
+in Debian's build and is difficult to integrate. VyOS debianizes the module
+manually:
 
-0. Install https://pypi.org/project/stdeb/
-1. `cd vyos-strongswan`
-2. `./configure --enable-python-eggs`
-3. `cd src/libcharon/plugins/vici/python`
-4. `make`
-5. `python3 setup.py --command-packages=stdeb.command bdist_deb`
+1. Install ``stdeb`` from PyPI (for example: ``pip3 install stdeb``).
+2. ``cd vyos-strongswan``
+3. ``./configure --enable-python-eggs``
+4. ``cd src/libcharon/plugins/vici/python``
+5. ``make``
+6. ``python3 setup.py --command-packages=stdeb.command bdist_deb``
 
-The package ends up in deb_dist dir.
+The package is created in the ``deb_dist`` directory.
 
-mdns-repeater
-^^^^^^^^^^^^^
+``mdns-repeater``
+-----------------
 
-This package doesn't exist in Debian. A debianized fork is kept at
-https://github.com/vyos/mdns-repeater
+This package does not exist in Debian. VyOS maintains a debianized fork at
+https://github.com/vyos/mdns-repeater.
 
 No special build procedure is required.
 
-udp-broadcast-relay
-^^^^^^^^^^^^^^^^^^^
+``udp-broadcast-relay``
+-----------------------
 
-This package doesn't exist in Debian. A debianized fork is kept at
-https://github.com/vyos/udp-broadcast-relay
+This package does not exist in Debian. VyOS maintain a debianized fork at
+https://github.com/vyos/udp-broadcast-relay.
 
 No special build procedure is required.
 
-hvinfo
-^^^^^^
+``hvinfo``
+----------
 
-A fork with packaging changes for VyOS is kept at https://github.com/vyos/hvinfo
+A fork with packaging changes for VyOS is available at https://github.com/vyos/hvinfo.
 
-The original repo is at https://github.com/dmbaturin/hvinfo
+The original repository is at https://github.com/dmbaturin/hvinfo.
 
-It's an Ada program and requires GNAT and gprbuild for building, dependencies
-are properly specified so just follow debuild's suggestions.
+It is an Ada program and requires GNAT and ``gprbuild``. Dependencies are
+properly specified; follow the suggestions from ``debuild``.