3 files changed, 75 insertions, 19 deletions
diff --git a/doc/apt-get.8.xml b/doc/apt-get.8.xml
index 931a4f313..a38a14e0c 100644
--- a/doc/apt-get.8.xml
+++ b/doc/apt-get.8.xml
@@ -575,6 +575,23 @@
      Configuration Item: <literal>Acquire::AllowInsecureRepositories</literal>.</para></listitem>
      </varlistentry>
 
+     <varlistentry><term><option>--allow-releaseinfo-changes</option></term>
+     <listitem><para>Allow the update command to continue downloading
+     data from a repository which changed its information of the release
+     contained in the repository indicating e.g a new major release.
+     APT will fail at the update command for such repositories until the
+     change is confirmed to ensure the user is prepared for the change.
+     See also &apt-secure; for details on the concept and configuration.
+     </para><para>
+     Specialist options
+     (<literal>--allow-releaseinfo-changes-</literal><replaceable>field</replaceable>)
+     exist to allow changes only for certain fields like <literal>origin</literal>,
+     <literal>label</literal>, <literal>codename</literal>, <literal>suite</literal>,
+     <literal>version</literal> and <literal>defaultpin</literal>. See also &apt-preferences;.
+
+     Configuration Item: <literal>Acquire::AllowReleaseInfoChanges</literal>.</para></listitem>
+     </varlistentry>
+
      <varlistentry><term><option>--show-progress</option></term>
      <listitem><para>Show user friendly progress information in the
      terminal window when packages are installed, upgraded or
diff --git a/doc/apt-secure.8.xml b/doc/apt-secure.8.xml
index 8ad249d7c..4f5d491f3 100644
--- a/doc/apt-secure.8.xml
+++ b/doc/apt-secure.8.xml
@@ -13,7 +13,7 @@
    &apt-email;
    &apt-product;
    <!-- The last update date -->
-   <date>2016-08-06T00:00:00Z</date>
+   <date>2017-04-12T00:00:00Z</date>
  </refentryinfo>
 
  <refmeta>
@@ -50,10 +50,20 @@
    that data like packages in the archive can't be modified by people who
    have no access to the Release file signing key. Starting with version 1.1
    <command>APT</command> requires repositories to provide recent authentication
-   information for unimpeded usage of the repository.
+   information for unimpeded usage of the repository. Since version 1.5 changes
+   in the information contained in the Release file about the repository need to be
+   confirmed before APT continues to apply updates from this repository.
    </para>
 
    <para>
+   Note: All APT-based package management front-ends like &apt-get;, &aptitude;
+   and &synaptic; support this authentication feature, so this manpage uses
+   <literal>APT</literal> to refer to them all for simplicity only.
+   </para>
+</refsect1>
+
+ <refsect1><title>Unsigned Repositories</title>
+   <para>
    If an archive has an unsigned Release file or no Release file at all
    current APT versions will refuse to download data from them by default
    in <command>update</command> operations and even if forced to download
@@ -83,16 +93,9 @@
    to <literal>true</literal> or for Individual repositories with the &sources-list;
    option <literal>allow-downgrade-to-insecure=yes</literal>.
    </para>
-
-   <para>
-   Note: All APT-based package management front-ends like &apt-get;, &aptitude;
-   and &synaptic; support this authentication feature, so this manpage uses
-   <literal>APT</literal> to refer to them all for simplicity only.
-   </para>
 </refsect1>
 
- <refsect1><title>Trusted Repositories</title>
-
+ <refsect1><title>Signed Repositories</title>
    <para>
    The chain of trust from an APT archive to the end user is made up of
    several steps. <command>apt-secure</command> is the last step in
@@ -162,7 +165,22 @@
    this mechanism can complement a per-package signature.</para>
 </refsect1>
 
- <refsect1><title>User Configuration</title>
+<refsect1><title>Information changes</title>
+   <para>
+   A Release file contains beside the checksums for the files in the repository
+   also general information about the repository like the origin, codename or
+   version number of the release.
+   </para><para>
+   This information is shown in various places so a repository owner should always
+   ensure correctness. Further more user configuration like &apt-preferences;
+   can depend and make use of this information. Since version 1.5 the user must
+   therefore explicitly confirm changes to signal that the user is sufficently
+   prepared e.g. for the new major release of the distribution shipped in the
+   repository (as e.g. indicated by the codename).
+   </para>
+</refsect1>
+
+<refsect1><title>User Configuration</title>
    <para>
    <command>apt-key</command> is the program that manages the list of keys used
    by APT to trust repositories. It can be used to add or remove keys as well
@@ -183,7 +201,7 @@
    </para>
 </refsect1>
 
-<refsect1><title>Archive Configuration</title>
+<refsect1><title>Repository Configuration</title>
    <para>
    If you want to provide archive signatures in an archive under your
    maintenance you have to:
diff --git a/doc/examples/configure-index b/doc/examples/configure-index
index a48d4cb99..8adef26a9 100644
--- a/doc/examples/configure-index
+++ b/doc/examples/configure-index
@@ -29,10 +29,20 @@
    and the syntax of configuration files and commandline options!
 */
 
-quiet "<INT>";
-quiet::NoUpdate "<BOOL>"; // never update progress information - included in -q=1
-quiet::NoProgress "<BOOL>"; // disables the 0% → 100% progress on cache generation and stuff
-quiet::NoStatistic "<BOOL>"; // no "42 kB downloaded" stats in update
+quiet "<INT>" {
+  NoUpdate "<BOOL>"; // never update progress information - included in -q=1
+  NoProgress "<BOOL>"; // disables the 0% → 100% progress on cache generation and stuff
+  NoStatistic "<BOOL>"; // no "42 kB downloaded" stats in update
+  ReleaseInfoChange "<BOOL>" // don't even print the notices if the info change is allowed
+  {
+    Origin "<BOOL>";
+    Label "<BOOL>";
+    Version "<BOOL>";
+    Codename "<BOOL>";
+    Suite "<BOOL>";
+    DefaultPin "<BOOL>";
+  };
+};
 
 // Options for APT in general
 APT
@@ -221,6 +231,20 @@ Acquire
 
   SameMirrorForAllIndexes "<BOOL>"; // use the mirror serving the Release file for Packages & co
 
+  AllowInsecureRepositories "<BOOL>";
+  AllowWeakRepositories "<BOOL>";
+  AllowDowngradeToInsecureRepositories "<BOOL>";
+  // allow repositories to change information potentally breaking user config like pinning
+  AllowReleaseInfoChange "<BOOL>"
+  {
+    Origin "<BOOL>";
+    Label "<BOOL>";
+    Version "<BOOL>"; // allowed by default
+    Codename "<BOOL>";
+    Suite "<BOOL>";
+    DefaultPin "<BOOL>";
+  };
+
   // HTTP method configuration
   http
   {
@@ -686,9 +710,6 @@ acquire::cdrom::mount "<DIR>";
 acquire::maxreleasefilesize "<INT>";
 acquire::queuehost::limit "<INT>";
 acquire::max-pipeline-depth "<INT>";
-acquire::allowinsecurerepositories "<BOOL>";
-acquire::allowweakrepositories "<BOOL>";
-acquire::allowdowngradetoinsecurerepositories "<BOOL>";
 acquire::progress::diffpercent "<BOOL>";
 acquire::gzipindexes "<BOOL>";
 acquire::indextargets::randomized "<BOOL>";