.. _5.0_Upgrading:

Upgrading to Buildbot 5.0 (not released)
========================================

Upgrading a Buildbot instance from 4.x to 5.0 may require some work to achieve.

The recommended upgrade procedure is as follows:

  - Upgrade to the last released BuildBot version in 4.x series.

  - Remove usage of the deprecated APIs.
    All usages of deprecated APIs threw a deprecation warning at the point of use.
    If the code does not emit deprecation warnings, it's in a good shape in this regard.
    You may need to run the master on a real workload in order to force all deprecated code paths to be exercised.

  - Upgrade to the latest Buildbot 5.0.x release.

  - (Optional) Upgrade to newest Buildbot 5.x.
    The newest point release will contain bug fixes and functionality improvements.

Testing support
===============

The ``build_files``, ``worker_env`` and ``worker_version`` arguments of
``TestBuildStepMixin.setup_step()`` have been removed. As a replacement, call
``TestBuildStepMixin.setup_build()`` before ``setup_step``.

HTTP service
============

The following methods of ``httpclientservice.HTTPClientService`` have been deprecated:

 - ``get``
 - ``delete``
 - ``post``
 - ``put``
 - ``updateHeaders``

As a replacement, use ``httpclientservice.HTTPSession`` and call corresponding methods on it.

Database connectors
===================

The internal API presented by the database connectors has been changed to return data classes
instead of Python dictionaries. To upgrade to the data classes simply access the data as class
attributes, not dictionary keys.

The following functions have been affected:

- ``BuildDataConnectorComponent`` ``getBuildData``, ``getBuildDataNoValue``, and ``getAllBuildDataNoValues``.
- ``BuildsConnectorComponent`` ``getBuild``, ``getBuildByNumber``, ``getPrevSuccessfulBuild``,
  ``getBuildsForChange``, ``getBuilds``, ``_getRecentBuilds``, and ``_getBuild``.
- ``BuildRequestsConnectorComponent`` ``getBuildRequest``, and ``getBuildRequests``.
- ``BuildsetsConnectorComponent`` ``getBuildset``, ``getBuildsets``, and ``getRecentBuildsets``.
- ``BuildersConnectorComponent`` ``getBuilder`` and ``getBuilders``.
- ``ChangesConnectorComponent`` ``getChange``, ``getChangesForBuild``, ``getChangeFromSSid``.
- ``ChangeSourcesConnectorComponent`` ``getChangeSource``, and ``getChangeSources``.
- ``LogsConnectorComponent`` ``getLog``, ``getLogBySlug``, and ``getLogs``.
- ``MastersConnectorComponent`` ``getMaster``, and ``getMasters``.
- ``ProjectsConnectorComponent`` ``get_project``, ``get_projects``.
- ``SchedulersConnectorComponent`` ``getScheduler``, and ``getSchedulers``.
- ``SourceStampsConnectorComponent`` ``getSourceStamp``, ``get_sourcestamps_for_buildset``,
  ``getSourceStampsForBuild``, and ``getSourceStamps``.
- ``StepsConnectorComponent`` ``getStep``, and ``getSteps``.
- ``TestResultsConnectorComponent`` ``getTestResult`` and ``getTestResults``.
- ``TestResultSetsConnectorComponent`` ``getTestResultSet``, and ``getTestResultSets``.
- ``UsersConnectorComponent`` ``getUser``, ``getUserByUsername``, and ``getUsers``.
- ``WorkersConnectorComponent`` ``getWorker``, and ``getWorkers``.

Reporters
=========

The ``add_logs`` argument of ``BuildStatusGenerator``, ``BuildStartEndStatusGenerator`` and
``BuildSetStatusGenerator`` has been removed. As a replacement, set ``want_logs_content`` of the
passed message formatter.