From 319ae65b93c8f575f3d374d742f55694fb1dbf89 Mon Sep 17 00:00:00 2001
From: Jeremy Stanley <fungi@yuggoth.org>
Date: Fri, 9 Aug 2019 21:18:43 +0000
Subject: [PATCH] Update documentation for Debian/Ubuntu mirror_info

Extend the Debian/Ubuntu mirror_info design to accommodate the
parameters required for sources.list entries, and more closely match
the scheme and terminology for them to what is described in the
sources.list(5) manpage.

Change-Id: I0e3cdfeaff838484a9dd0a8cace134c9f8e94650
---
 doc/source/mirror.rst | 68 +++++++++++++++++++++++++++++++++----------
 1 file changed, 52 insertions(+), 16 deletions(-)

diff --git a/doc/source/mirror.rst b/doc/source/mirror.rst
index 91bcafa02..eb2135651 100644
--- a/doc/source/mirror.rst
+++ b/doc/source/mirror.rst
@@ -29,17 +29,31 @@ For example:
      opensuse:
        url: https://{{ zuul_site_local_mirror_host }}/opensuse
      debian:
-       - url: https://{{ zuul_site_local_mirror_host }}/debian
+       - type: deb
+         options:
+           trusted: true
+         url: https://{{ zuul_site_local_mirror_host }}/debian
+         suites: ['stretch', 'buster']
          components: ['main']
-       - url: https://{{ zuul_site_local_mirror_host }}/debian-security
+       - type: deb
+         options:
+           trusted: true
+         url: https://{{ zuul_site_local_mirror_host }}/debian-security
+         suites: ['stretch/updates', 'buster/updates']
          components: ['main']
      ubuntu:
-       - url: https://{{ zuul_site_local_mirror_host }}/ubuntu
+       - type: deb
+         options:
+           trusted: true
+         url: https://{{ zuul_site_local_mirror_host }}/ubuntu
+         suites: ['xenial', 'bionic']
          components: ['main', 'universe']
-         trusted: true
-       - url: https://{{ zuul_site_local_mirror_host }}/ubuntu-security
+       - type: deb
+         options:
+           trusted: true
+         url: https://{{ zuul_site_local_mirror_host }}/ubuntu
+         suites: ['xenial-security', 'bionic-security']
          components: ['main', 'universe']
-         trusted: true
      dockerhub:
        url: https://{{ zuul_site_local_mirror_host }}:8082/
 
@@ -87,21 +101,32 @@ For example:
       accomodates mirror systems which may have a security mirror at a
       different URL.
 
+      .. zuul:rolevar:: type
+
+         The type for a Debian mirror (usually either ``deb`` or
+         ``deb-src``).
+
+      .. zuul:rolevar:: options
+         :type: dict
+
+         Mirror options, for example add ``trusted: yes`` in order
+         to trust unsigned APT mirrors.
+
       .. zuul:rolevar:: url
 
          The URL for a Debian mirror.
 
+      .. zuul:rolevar:: suites
+         :type: list
+
+         The list of suites for a Debian mirror.
+
       .. zuul:rolevar:: components
          :type: list
 
          A list of components available in this mirror (e.g.,
          ``main``, ``contrib``).
 
-      .. zuul:rolevar:: trusted
-         :default: False
-
-         Set to True in order to tag APT mirrors as trusted.
-
    .. zuul:rolevar:: ubuntu
       :type: list
 
@@ -109,21 +134,32 @@ For example:
       accomodates mirror systems which may have a security mirror at a
       different URL.
 
+      .. zuul:rolevar:: type
+
+         The type for an Ubuntu mirror (usually either ``deb`` or
+         ``deb-src``).
+
+      .. zuul:rolevar:: options
+         :type: dict
+
+         Mirror options, for example add ``trusted: yes`` in order
+         to trust unsigned APT mirrors.
+
       .. zuul:rolevar:: url
 
          The URL for an Ubuntu mirror.
 
+      .. zuul:rolevar:: suites
+         :type: list
+
+         The list of suites for an Ubuntu mirror.
+
       .. zuul:rolevar:: components
          :type: list
 
          A list of components available in this mirror (e.g.,
          ``main``, ``contrib``).
 
-      .. zuul:rolevar:: trusted
-         :default: False
-
-         Set to True in order to tag APT mirrors as trusted.
-
    .. zuul:rolevar:: dockerhub
 
       .. zuul:rolevar:: url