split docs to subdirectories

Fixes: https://pagure.io/koji/issue/1715

docs/source/migrations/migrating_to_1.10.rst

@@ -0,0 +1,84 @@
+Migrating to Koji 1.10
+======================
+
+.. reStructured Text formatted
+
+The 1.10 release of Koji includes a few changes that you should consider when
+migrating.
+
+DB Updates
+----------
+
+The new ``tag_extra`` table tracks extra data for tags.
+
+There is a new entry in the ``channels`` table and some additions and updates to
+the ``archivetypes`` table.
+
+As in previous releases, we provide a migration script that updates the
+database.
+
+::
+
+    # psql koji koji  </usr/share/doc/koji-1.10.0/docs/schema-upgrade-1.9-1.10.sql
+
+
+Command line changes
+--------------------
+
+A few commands support new arguments
+
+``maven-build``
+    * ``--ini``     : Pass build parameters via a .ini file
+    * ``--section`` : Get build parameters from this section of the .ini
+
+``wrapper-rpm``
+    * ``--ini``     : Pass build parameters via a .ini file
+    * ``--section`` : Get build parameters from this section of the .ini
+
+``import``
+    * ``--link``    : Attempt to hardlink instead of uploading
+
+``list-tagged``
+    * ``--latest-n``: Only show the latest N builds/rpms
+
+``list-history``
+    * ``--watch``   : Monitor history data
+
+``edit-tag``
+    * ``--extra``   : Set tag extra option
+
+``list-tasks``
+    * ``--user``    : Only tasks for this user
+    * ``--arch``    : Only tasks for this architecture
+    * ``--method``  : Only tasks of this method
+    * ``--channel`` : Only tasks in this channel
+    * ``--host``    : Only tasks for this host
+
+``download-build``
+    * ``--task-id`` : Interpret id as a task id
+
+And there are three new commands
+
+* ``image-build-indirection``
+* ``maven-chain``
+* ``runroot``
+
+
+Other Configuration changes
+---------------------------
+
+The Koji web interface can now treat ``extra-footer.html`` as a Cheetah
+template. This behavior can be enabled by setting the ``LiteralFooter`` option
+to ``False`` in the kojiweb config.
+
+
+RPC API Changes
+---------------
+
+The ``readTaggedBuilds`` and ``readTaggedRPMS`` now treat an integer value for
+the optional latest argument differently. Before it was simply treated as a
+boolean flag, which if true caused the call to return only the latest build for
+each package. Now, if the value is a positive integer N, it will return the N
+latest builds for each package. The behavior is unchanged for other values.
+
+New rpc calls: ``chainMaven``, ``buildImageIndirection``, and ``mergeScratch``

docs/source/migrations/migrating_to_1.11.rst

@@ -0,0 +1,108 @@
+Migrating to Koji 1.11
+======================
+
+.. reStructured Text formatted
+
+The 1.11 release of Koji includes a several changes that you should consider when
+migrating.
+
+DB Updates
+----------
+
+There are a number of new tables and columns to support content generators. Here is a summary:
+    * The ``btype`` table tracks the known btypes [LINK] in the system
+    * The ``build_types`` table links builds to their btype(s)
+    * The ``content_generator`` table tracks the known content generators in the system
+    * The ``cg_users`` table tracks which users have access to which content generators
+    * The ``buildroot`` table now tracks more generic buildroots
+    * The ``standard_buildroot`` table tracks data for "normal" koji buildroots
+    * Several tables now have an ``extra`` column that stores json data
+    * There are several new entries in the ``archivetypes`` table
+    * The ``image_listing`` table has been replace by the more general ``archive_rpm_components`` table
+    * The new ``archive_components`` complements this and tracks non-rpm components
+
+As in previous releases, we provide a migration script that updates the
+database.
+
+::
+
+    # psql koji koji  </usr/share/doc/koji-1.11.0/docs/schema-upgrade-1.10-1.11.sql
+
+Note: prior to this release, we had some interim update scripts:
+    * schema-update-cgen.sql
+    * schema-update-cgen2.sql
+
+Most users should not need these scripts. The new schema upgrade script includes
+those changes.
+
+
+Command line changes
+--------------------
+
+The ``help`` command now shows a categorized list of commands.
+
+The ``hello`` command now reports the authentication type.
+
+Several commands support new arguments. Here are the notable changes:
+
+``add-tag``
+    * ``--extra``       : Set an extra option for tag at creation
+
+``watch-task``
+    * Supports several new task selection options
+
+``download-build``
+    * ``--rpm``         : Used to download a particular rpm by name
+
+``runroot``
+    * ``--new-chroot``  : Run command with the --new-chroot (systemd-nspawn) option to mock
+
+
+And there are five new commands
+
+* ``assign-task``
+* ``import-cg``
+* ``grant-cg-access``
+* ``revoke-cg-access``
+* ``spin-livemedia``
+
+
+Client configuration options
+----------------------------
+
+The command line and several other tools support the following new configuration options:
+    * ``use_old_ssl``   : Use the old ssl code instead of python-requests
+    * ``no_ssl_verify``   : Disable certificate verification for https connections
+    * ``upload_blocksize`` : Override the blocksize for uploads
+    * ``krb_rdns``      : Use the fqdn of the server when authenticating via kerberos
+
+The ``ca`` option is deprecated and no longer required for ssl authentication (``serverca`` is still required).
+
+Even if not using ssl authentication, the ``serverca`` option, if specified, is used to verify the certificate of the
+server.
+
+
+Other Configuration changes
+---------------------------
+
+The Koji web interface supports the following new configuration options:
+    * ``KrbRDNS``       : Use the fqdn of the server when authenticating via kerberos
+    * ``LoginDisabled`` : Hide the login link at the top of the page
+
+
+RPC API Changes
+---------------
+
+New rpc calls:
+    * ``CGImport``      : Used by content generators
+    * ``getBuildType``  : Returns typeinfo for a build
+    * ``listBTypes``    : List the known btypes for the system
+    * ``addBType``      : Adds a new btype
+    * ``grantCGAccess`` : Grants a user content generator access
+    * ``revokeCGAccess`` : Revokes content generator access
+
+Changes to calls
+    * Several information calls now return additional fields
+    * ``getRPMDeps`` returns optional deps
+    * ``listTasks`` supports new selection options
+    * ``getLoggedInUser`` includes an authtype field

docs/source/migrations/migrating_to_1.12.rst

@@ -0,0 +1,81 @@
+Migrating to Koji 1.12
+======================
+
+..
+  reStructured Text formatted
+
+The 1.12 release of Koji includes a several changes that you should consider when
+migrating.
+
+DB Updates
+----------
+
+There is a minor update to support the dist-repos feature:
+    * The ``repo`` table now has a ``dist`` column
+
+Additionally, the schema explicitly adds the ``image`` permission to the
+permissions table, correcting an old oversight.
+
+As in previous releases, we provide a migration script that updates the
+database.
+
+::
+
+    # psql koji koji  </usr/share/doc/koji/docs/schema-upgrade-1.11-1.12.sql
+
+
+Command line changes
+--------------------
+
+The ``import-sig`` command now now supports a ``--write`` option to immediately
+write out a signed copy.
+
+The ``write-signed-rpm`` command previously (and confusingly) only accepted
+nvrs as arguments (i.e. builds not rpms). Now it accepts either nvras or nvrs
+(rpms or builds).
+
+The ``clone-tag`` command has been refactored. It supports many more options
+and should execute much faster than before.
+
+The new ``dist-repo`` command creates rpm repos suitable for distribution.
+
+The new ``save-failed-tree`` command allows the a task owner (or admin)
+to download information from the buildroot of a failed build. This feature
+requires the ``save_failed_tree`` plugin to be enabled on the hub and builders.
+
+
+Configuration
+-------------
+
+The only configuration changes are for the ``save-failed-tree`` plugins (hub
+and builder). Each has its own configuration file. See :doc:`../plugins`
+
+The hub accepts a new ``CheckClientIP`` option (default True) to indicate
+whether authentication credentials should be tied to the client's IP address.
+(For some proxy setups, this may need to be set to False).
+
+
+RPC API Changes
+---------------
+
+New rpc calls:
+
+``listPackagesSimple``
+    handles a limited subset of the
+    functionality provided by the ``listPackages`` call
+
+``distRepo``
+    triggers generation of a distribution repo
+
+Changes to calls:
+    * repo related calls (e.g. ``repoInfo`` now include a boolean ``dist``
+      field
+    * the ``editTag2`` call can now remove tag_extra data if the
+      ``remove_extra`` keyword argument is used
+    * the listTaskOutput call supports a new ``all_volumes`` keyword argument.
+      If true, the results are extended to deal with files in same relative paths
+      on different volumes.
+    * the ``getTaskResult`` call takes an optional boolean ``raise_fault``
+      argument
+    * the ``taskWaitResults`` call takes an optional ``canfail`` argument
+      to indicate subtasks which can fail without raising an exception

docs/source/migrations/migrating_to_1.13.rst

@@ -0,0 +1,49 @@
+Migrating to Koji 1.13
+======================
+
+..
+  reStructured Text formatted
+
+The 1.13 release of Koji includes several changes that you should consider when
+migrating.
+
+DB Updates
+----------
+
+We have increased the length limit for tag names and there is a minor schema
+change to support this.
+
+As in previous releases, we provide a migration script that updates the
+database.
+
+::
+
+    # psql koji koji  </usr/share/doc/koji/docs/schema-upgrade-1.12-1.13.sql
+
+
+Packaging changes
+-----------------
+
+Because the CLI and base library now support both python2 and python3, the core
+libs and most of the cli code have moved to separate packages for each major
+Python version:
+
+    * python2-koji
+    * python3-koji
+
+The main koji package still contains the (now much smaller) koji script, and
+requires either python2-koji or python3-koji, depending on whether python3
+support is enabled.
+
+The CLI now also supports plugins, and two commands (runroot and
+save-failed-tree) have moved to the `python[23]-koji-cli-plugins`
+subpackages. If you need these subcommands, you may need to explicitly install
+the appropriate koji-cli-plugins package.
+
+
+Other changes
+-------------
+
+There are numerous other changes in 1.13 that should not have a direct impact
+on migration. For details see:
+:doc:`../release_notes/release_notes_1.13`

docs/source/migrations/migrating_to_1.14.rst

@@ -0,0 +1,39 @@
+Migrating to Koji 1.14
+======================
+
+..
+  reStructured Text formatted
+
+You should consider the following changes when migrating to 1.14:
+
+DB Updates
+----------
+
+The schema updates this time are minor
+
+   * dropped unused ``log_messages`` table
+   * new standard entries in the ``archivetypes`` table
+
+As in previous releases, we provide a migration script that updates the
+database.
+
+::
+
+    # psql koji koji  </usr/share/doc/koji/docs/schema-upgrade-1.13-1.14.sql
+
+
+Dropped mod_python support
+--------------------------
+
+Koji's support for mod_python has been deprecated for many years. If you are
+still relying on mod_python, you will need to switch to mod_wsgi.
+
+See: :doc:`migrating_to_1.7`
+
+
+Other changes
+-------------
+
+There are numerous other changes in 1.14 that should not have a direct impact
+on migration. For details see:
+:doc:`../release_notes/release_notes_1.14`

docs/source/migrations/migrating_to_1.15.rst

@@ -0,0 +1,20 @@
+Migrating to Koji 1.15
+======================
+
+..
+  reStructured Text formatted
+
+The update from to 1.15 is comparatively light from a migration perspective.
+
+DB Updates
+----------
+
+There are no schema updates in 1.15.
+
+
+Other changes
+-------------
+
+There are numerous other changes in 1.15 that should not have a direct impact
+on migration. For details see:
+:doc:`../release_notes/release_notes_1.15`

docs/source/migrations/migrating_to_1.16.rst

@@ -0,0 +1,32 @@
+Migrating to Koji 1.16
+======================
+
+..
+  reStructured Text formatted
+
+You should consider the following changes when migrating to 1.16:
+
+DB Updates
+----------
+
+This release has schema changes to support tracking history for hosts.
+
+    * new table: ``host_config``
+    * some fields from the ``host`` table have moved to ``host_config``
+    * the ``host_channels`` table now has versioning data like the other
+      versioned tables
+
+As in previous releases, we provide a migration script that updates the
+database.
+
+::
+
+    # psql koji koji  </usr/share/doc/koji/docs/schema-upgrade-1.15-1.16.sql
+
+
+Other changes
+-------------
+
+There are numerous other changes in 1.16 that should not have a direct impact
+on migration. For details see:
+:doc:`../release_notes/release_notes_1.16`

docs/source/migrations/migrating_to_1.17.rst

@@ -0,0 +1,30 @@
+Migrating to Koji 1.17
+======================
+
+..
+  reStructured Text formatted
+
+You should consider the following changes when migrating to 1.17:
+
+DB Updates
+----------
+
+This release some minor schema changes
+
+    * the ``tag_external_repos`` table has a new ``merge_mode`` column
+    * the ``build_target.name`` column is now a TEXT field rather than VARCHAR
+
+As in previous releases, we provide a migration script that updates the
+database.
+
+::
+
+    # psql koji koji  </usr/share/doc/koji/docs/schema-upgrade-1.16-1.17.sql
+
+
+Other changes
+-------------
+
+There are numerous other changes in 1.17 that should not have a direct impact
+on migration. For details see:
+:doc:`../release_notes/release_notes_1.17`

docs/source/migrations/migrating_to_1.18.rst

@@ -0,0 +1,42 @@
+Migrating to Koji 1.18
+======================
+
+..
+  reStructured Text formatted
+
+You should consider the following changes when migrating to 1.18:
+
+DB Updates
+----------
+
+This release has a few schema changes:
+
+    * Several new indexes to speed operations
+    * A ``cg_id`` field has been added to the ``build`` table
+    * A new ``build_reservations`` table
+    * A new ``build_notifications_block`` table
+    * Updates to the data in the ``archivetypes`` table
+
+As in previous releases, we provide a migration script that updates the
+database.
+
+::
+
+    # psql koji koji  </usr/share/doc/koji/docs/schema-upgrade-1.17-1.18.sql
+
+
+More granular permissions
+-------------------------
+
+The new ``host``, ``tag``, ``target`` permissions allow access to a number of
+actions that were previously admin-only.
+Koji administrators should consider using these to reduce the number of users
+with full ``admin`` permission.
+
+
+Other changes
+-------------
+
+There are numerous other changes in 1.18 that should not have a direct impact
+on migration. For details see:
+:doc:`../release_notes/release_notes_1.18`

docs/source/migrations/migrating_to_1.19.rst

@@ -0,0 +1,33 @@
+Migrating to Koji 1.19
+======================
+
+..
+  reStructured Text formatted
+
+You should consider the following changes when migrating to 1.19:
+
+DB Updates
+----------
+
+This release has a few schema changes:
+
+    * A new ``tag_package_owners`` table
+    * A new ``user_krb_principals`` table
+    * Updates to the data in the ``archivetypes`` table
+    * Updates to the data in the ``permissions`` table
+    * The ``content_generator`` table now enforces unique strings in the ``names`` field
+
+As in previous releases, we provide a migration script that updates the
+database.
+
+::
+
+    # psql koji koji  </usr/share/doc/koji/docs/schema-upgrade-1.18-1.19.sql
+
+
+Other changes
+-------------
+
+There are numerous other changes in 1.19 that should not have a direct impact
+on migration. For details see:
+:doc:`../release_notes/release_notes_1.19`

docs/source/migrations/migrating_to_1.7.rst

@@ -0,0 +1,148 @@
+Migrating to Koji 1.7
+=====================
+
+.. reStructured Text formatted
+
+The 1.7 release of Koji contains changes that will require a little extra
+work when updating. These changes are:
+
+* DB schema updates to support storage volumes
+* The change from mod_python to mod_wsgi
+* The introduction of a separate configuration file for koji-web
+* Changes to url options
+
+DB Schema Updates
+-----------------
+
+The 1.7 release adds two new tables to the database. The ``volume`` table tracks
+the names of available storage volumes, and the ``tag_updates`` table tracks
+changes to tags that are not easily calculated from other tables. There is
+also a new field in the ``build`` table, ``volume_id``, which indicates which
+volume a build is stored on.
+
+As in previous releases, we provide a migration script that updates the
+database.
+
+::
+
+    # psql koji koji  </usr/share/doc/koji-1.7.0/docs/schema-upgrade-1.5-1.7.sql
+
+
+mod_python and mod_wsgi
+-----------------------
+
+Koji now defaults to using mod_wsgi to interface with httpd. Support for
+mod_python is _deprecated_ and will disappear in a future version of Koji.
+Koji administrators can opt to stay on mod_python for now, but some minor
+configuration changes will be required.
+
+Migrating to mod_wsgi
+^^^^^^^^^^^^^^^^^^^^^
+
+The mod_wsgi package is now required for both koji-hub and koji-web. Folks
+running RHEL5 can find mod_wsgi in EPEL.
+
+You will need to adjust your http config for both koji-hub and koji-web. Our
+example config files default to mod_wsgi. To adapt your existing config, you
+will need to:
+
+* For both the koji-hub and koji-web/scripts directories:
+    * add ``Options ExecCGI``
+    * change ``SetHandler`` from mod_python to wsgi-script
+* Ensure that the koji-web Alias points to wsgi_publisher.py
+* If you have not already, migrate all koji-hub PythonOptions to hub.conf
+* Migrate all koji-web PythonOptions to web.conf (see later section)
+
+Staying on mod_python
+^^^^^^^^^^^^^^^^^^^^^
+
+Support for mod_python is _deprecated_ and will disappear in a future version
+of Koji.
+
+While we have made efforts to maintain mod_python compatibility, there are
+a few configuration changes you will need to make.
+
+The koji-hub http config should continue to function without modification.
+
+The koji-web http config will, at minimum, require the following changes:
+
+* Ensure that the koji-web ``Alias`` points to wsgi_publisher.py
+* Change koji-web's ``PythonHandler`` setting to wsgi_publisher
+
+Our example http configurations contain commented examples of mod_python
+configuration.
+
+Even if you stay on mod_python, we recommend that you migrate away from using
+PythonOptions and place your configuration in web.conf and hub.conf.
+
+
+Web Configuration
+-----------------
+
+Starting with version 1.7, koji-web uses a separate configuration file, rather
+than PythonOptions embedded in the httpd config. The location of the new file
+is:
+
+::
+
+    /etc/kojiweb/web.conf
+
+The web.conf file is an ini-style configuration file. Options should be placed
+in the [web] section. All previous options accepted via PythonOptions are
+accepted in web.conf. Please see the example web.conf file.
+
+
+Custom Config File Location
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The location of web.conf can be specified in the httpd configuration. To
+specify the location under mod_wsgi, use:
+
+::
+
+    SetEnv koji.web.ConfigFile /path/to/web.conf
+
+Under mod_python, use:
+
+::
+
+    PythonOption koji.web.ConfigFile /path/to/web.conf
+
+If you opt to stay on mod_python, the server will continue to process the old
+PythonOptions. To ease migration, it does so by default unless the
+koji.web.ConfigFile PythonOption is specified. In order to use web.conf under
+mod_python, you *must* specify koji.web.ConfigFile in your http config.
+
+We strongly recommend moving to web.conf. The server will issue a warning at
+startup if web.conf is not in use.
+
+
+Changes to url options
+----------------------
+
+The pkgurl option has been removed from the koji command line tool and from
+the build daemon (kojid). The url for packages is deduced from the topurl
+option, which should point to the top of the /mnt/koji tree.
+
+Any config files that specify pkgurl (e.g. ~/.koji/config, /etc/koji.conf, or
+/etc/kojid/kojid.conf) will need to be adjusted.
+
+Similarly, the kojiweb config options KojiPackagesURL, KojiMavenURL, and
+KojiImagesURL have been dropped in favor of the new option KojiFilesURL.
+
+
+Additional Notes
+----------------
+
+Split Storage
+^^^^^^^^^^^^^
+
+Apart from the schema changes, no other migration steps are required for the
+split storage feature. By default, builds are stored in the normal location.
+
+Web Themes
+^^^^^^^^^^
+
+Using the old method (httpd aliases for koji static content) should continue
+to work. For (brief) instructions on the new method, see the README file under
+koji-web/static/themes.

docs/source/migrations/migrating_to_1.8.rst

@@ -0,0 +1,125 @@
+Migrating to Koji 1.8
+=====================
+
+.. reStructured Text formatted
+
+The 1.8 release of Koji refactors how images (livecd and appliance) are stored
+in the database and on disc. These changes will require a little extra work
+when updating.
+
+There have also been some changes to the command line.
+
+Finally, kojira accepts some new options.
+
+DB Schema Updates
+-----------------
+
+Previous to 1.8, images were stored in separately from other builds, both in
+the database and on disc. The new schema adds new tables: ``image_builds``,
+``image_listing``, and ``image_archives``.
+
+The following tables are now obsolete: ``imageinfo`` and ``imageinfo_listing``.
+However you should not drop these tables until you have migrated your image
+data.
+
+As in previous releases, we provide a migration script that updates the
+database.
+
+::
+
+    # psql koji koji  </usr/share/doc/koji-1.8.0/docs/schema-upgrade-1.7-1.8.sql
+
+Note that the SQL script does not (and can not) automatically migrate your old
+image data to the new tables. After applying the schema changes, you can
+migrate old images using the ``migrateImage`` hub call. This method is necessary
+because the new schema requires each image to have a name, version, and release
+value. The values for name and version cannot be automatically guessed.
+
+
+Migrating your old images
+-------------------------
+
+If you have old images, you can migrate them to the new system using the
+``migrateImage`` hub call. This call requires admin privilege and must also be
+enabled with the ``EnableImageMigration`` configuration option in ``hub.conf``.
+
+The signature of the call is:
+
+::
+
+    migrateImage(old_image_id, name, version)
+
+This call can made from the command line:
+
+::
+
+    # koji call migrateImage 45 my_livecd 1.1
+
+
+Cleaning up
+-----------
+
+After you have migrated any necessary images to the new system, you may want to
+remove the old database tables and filesystem directories. This step is
+*optional*. If you want to leave the old data around, it will not affect Koji.
+
+Before you take any of the following actions, please *make sure* that you have
+migrated any desired images.
+
+Removing the old data is simply a matter of dropping tables and deleting files.
+
+::
+
+    koji=> DROP TABLE imageinfo_listing;
+    koji=> DROP TABLE imageinfo;
+    # rm -rf /mnt/koji/images
+
+
+Command line changes
+--------------------
+
+For clarity and consistency, all of the ``-pkg`` commands have been renamed to
+``-build`` commands.
+
+::
+
+    latest-pkg -> latest-build
+    move-pkg -> move-build
+    tag-pkg -> tag-build
+    untag-pkg -> untag-build
+
+For backwards compatibility, the old commands names are also recognized.
+
+A new command has been added, ``remove-pkg``.
+
+Several commands have been modified to support images.
+
+The ``spin-livecd`` and ``spin-appliance`` commands now require additional
+arguments. These arguments specify the name and version to use for the image.
+
+
+New kojira options
+------------------
+
+The following options are new to kojira:
+
+::
+
+    max_delete_processes
+    max_repo_tasks_maven
+
+Previously, kojira ran as a single process and repo deletions could potentially
+slow things down (particularly for Maven-enabled repos). Now kojira spawns
+a separate process to handle these deletions. The ``max_delete_processes``
+determines how many such processes it will launch at one time.
+
+When Maven-enabled repos are in use, they can potentially take a very long time
+to regenerate. If a number of these pile up it can severely slow down
+regeneration of non-Maven repos. The ``max_repo_tasks_maven`` limits how many
+Maven repos kojira will attempt to regenerate at once.
+
+Also the following kojira option has been removed:
+
+::
+
+    prune_batch_size

docs/source/migrations/migrating_to_1.9.rst

@@ -0,0 +1,86 @@
+Migrating to Koji 1.9
+=====================
+
+.. reStructured Text formatted
+
+The 1.9 release of Koji includes a few changes that you should consider when
+migrating.
+
+DB Updates
+----------
+
+ImageFactory support introduced some new archive types. These have been added to
+the ``archivetypes`` table. The inaccurate ``vmx`` entry has been removed.
+
+As in previous releases, we provide a migration script that updates the
+database.
+
+::
+
+    # psql koji koji  </usr/share/doc/koji-1.9.0/docs/schema-upgrade-1.8-1.9.sql
+
+
+Command line changes
+--------------------
+
+The command line interface handles configuration files a little differently. Old
+configs should work just fine, but now there are new options and enhancements.
+
+In addition to the main configuration files, the koji cli now checks for
+``/etc/koji.conf.d`` and ``~/.koji/config.d`` directories and loads any
+``*.conf`` files contained within. Also if the user specifies a directory with
+the ``-c/--config`` option, then that directory will be processed similarly.
+
+The command line supports a new ``-p/--profile`` option to select alternate
+configuration profiles without having to link or rename the koji executable.
+
+The new ``image-build`` command is used to generate images using ImageFactory.
+The older spin-appliance command is now deprecated.
+
+The ``mock-config`` command no longer requires a name argument. You can still
+specify one
+if you want to override the default choice. It also supports new options. The
+``--latest`` option causes the resulting mock config to reference the
+``latest`` repo (a varying symlink). The ``--target`` option allows generating
+the config from a target name.
+
+Other command line changes include:
+* a new ``download-logs`` command
+* the ``list-groups`` command now accepts event args
+* the ``taginfo`` command now reports the list of comps groups for the tag
+* the fast upload feature is now used automatically if the server supports it
+
+Other Configuration changes
+---------------------------
+
+There are also some minor configuration changes in other parts of Koji.
+
+In ``kojid`` the time limit for rpm builds is now configurable via the
+``rpmbuild_timeout`` setting in ``kojid.conf``. The default is 24 hours.
+
+The ``koji-gc`` tool supports two new configuration options. The ``krbservice``
+option allows you to specify the kerberos service for authentication, and the
+``email_domain`` option allows you to specify the email domain for sending gc
+notices.
+
+The messagebus hub plugin now supports ``timeout`` and ``heartbeat`` options
+for the message bus connection.
+
+
+RPC API Changes
+---------------
+
+Most of these changes are extensions, though some of the host-only call
+changes are incompatible.
+
+The ``tagHistory`` call accepts a new named boolean option (``active``) to
+select only active/inactive entries. It also now reports the additional fields
+``maven_build_id`` and ``win_build_id`` if builds are maven or win builds
+respectively.
+
+New rpc calls: ``buildImageOz``, ``host.completeImageBuild``, and
+``host.evalPolicy``.
+
+The host-only calls ``host.moveImageBuildToScratch`` and ``host.importImage``
+no longer accept the ``rpm_results`` argument. The rpm results can be embedded
+in the regular ``results`` argument.

docs/source/migrations/migrations.rst

@@ -0,0 +1,20 @@
+==========
+Migrations
+==========
+
+.. toctree::
+    :maxdepth: 1
+
+    migrating_to_1.19
+    migrating_to_1.18
+    migrating_to_1.17
+    migrating_to_1.16
+    migrating_to_1.15
+    migrating_to_1.14
+    migrating_to_1.13
+    migrating_to_1.12
+    migrating_to_1.11
+    migrating_to_1.10
+    migrating_to_1.9
+    migrating_to_1.8
+    migrating_to_1.7