[pve-devel] [PATCH v3 docs 08/10] Overhaul Package Repositories

[Stefan Reiter]

On 2/5/20 3:17 PM, Aaron Lauterer wrote:
> improve phrasing, align style of CLI commands
> 
> Signed-off-by: Aaron Lauterer <a.lauterer at proxmox.com>
> ---
> v2 -> v3:
> rebased on current master
> 
>   pve-package-repos.adoc | 143 +++++++++++++++++++++--------------------
>   1 file changed, 74 insertions(+), 69 deletions(-)
> 
> diff --git a/pve-package-repos.adoc b/pve-package-repos.adoc
> index 078de95..e11f8ec 100644
> --- a/pve-package-repos.adoc
> +++ b/pve-package-repos.adoc
> @@ -5,18 +5,16 @@ ifdef::wiki[]
>   :pve-toplevel:
>   endif::wiki[]
>   
> -All Debian based systems use
> -http://en.wikipedia.org/wiki/Advanced_Packaging_Tool[APT] as package
> -management tool. The list of repositories is defined in
> -`/etc/apt/sources.list` and `.list` files found inside
> -`/etc/apt/sources.d/`. Updates can be installed directly using
> -`apt-get`, or via the GUI.
> -
> -Apt `sources.list` files list one package repository per line, with
> -the most preferred source listed first. Empty lines are ignored, and a
> -`#` character anywhere on a line marks the remainder of that line as a
> -comment. The information available from the configured sources is
> -acquired by `apt-get update`.
> +{pve} uses http://en.wikipedia.org/wiki/Advanced_Packaging_Tool[APT] as package
> +management tool like any other Debian-based system. Repositories are defined in

... as *its* package management tool ...

> +the file `/etc/apt/sources.list` and in `.list` files placed in
> +`/etc/apt/sources.list.d/`.
> +
> +Each line defines a package repository. The preferred source must come first.
> +Empty lines are ignored. A `#` character anywhere on a line marks the remainder
> +of that line as a comment. The available packages from a repository are acquired
> +by running `apt-get update`. Updates can be installed directly using `apt-get`,
> +or via the GUI.
>   
>   .File `/etc/apt/sources.list`
>   ----
> @@ -28,7 +26,7 @@ deb http://security.debian.org/debian-security buster/updates main contrib
>   ----
>   // FIXME for 7.0: change security update suite to bullseye-security
>   
> -In addition, {pve} provides three different package repositories.
> +{pve} additionally provides three different package repositories.
>   
>   [[sysadmin_enterprise_repo]]
>   {pve} Enterprise Repository
> @@ -44,29 +42,25 @@ enabled by default:
>   deb https://enterprise.proxmox.com/debian/pve buster pve-enterprise
>   ----
>   
> -As soon as updates are available, the `root at pam` user is notified via
> -email about the available new packages. On the GUI, the change-log of
> -each package can be viewed (if available), showing all details of the
> -update. So you will never miss important security fixes.
> -
> -Please note that you need a valid subscription key to access this
> -repository. We offer different support levels, and you can find further
> -details at https://www.proxmox.com/en/proxmox-ve/pricing.
> +The `root at pam` user is notified via email about available updates. Click the
> +'Changelog' button in the GUI to see more details about the selected update.

This email notification also happens for non-enterprise repositories, 
doesn't it? If so, it might make sense to move it to the section above.

>   
> -NOTE: You can disable this repository by commenting out the above line
> -using a `#` (at the start of the line). This prevents error messages
> -if you do not have a subscription key. Please configure the
> -`pve-no-subscription` repository in that case.
> +You need a valid subscription key to access the `pve-enterprise` repository.
> +Different support levels are available. Further details can be found at
> +https://www.proxmox.com/en/proxmox-ve/pricing.
>   
> +NOTE: You can disable this repository by commenting out the above line using a
> +`#` (at the start of the line). This prevents error messages if you do not have
> +a subscription key. Please configure the `pve-no-subscription` repository in
> +that case.
>   
>   [[sysadmin_no_subscription_repo]]
>   {pve} No-Subscription Repository
>   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>   
> -As the name suggests, you do not need a subscription key to access
> -this repository. It can be used for testing and non-production
> -use. Its not recommended to run on production servers, as these
> -packages are not always heavily tested and validated.
> +This is the recommended repository for testing and non-production use. The
> +packages are not headily tested and validated. You don't need a subscription key

Typo in 'headily', how about in general:

   Its packages are not as heavily tested and validated.

We hopefully do test all of our packages, just not *as* heavily ;)

> +to access the `pve-no-subscription` repository.
>   
>   We recommend to configure this repository in `/etc/apt/sources.list`.
>   
> @@ -88,26 +82,25 @@ deb http://security.debian.org/debian-security buster/updates main contrib
>   {pve} Test Repository
>   ~~~~~~~~~~~~~~~~~~~~~~
>   

[snip]