.. _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``.

Non-reconfigurable services
===========================

Raising ``NotImplementedError`` from ``reconfigServiceWithSibling`` or ``reconfigService`` service
functions has been deprecated. Use ``canReconfigWithSibling()`` that returns ``False`` as a
replacement.

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.

Build factories
===============

``BuildFactory`` ``workdir`` attribute no longer supports callables. As a replacement, use a
renderable instead.

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``.

``DataConnector.produceEvent()`` has been deprecated. The replacement is update methods from the
data API.

Schedulers
==========

Old location of ``Dependent`` scheduler has been removed. Instead of
``buildbot.schedulers.basic.Dependent`` use ``buildbot.plugins.schedulers.Dependent``.

``buildbot.schedulers.base.BaseScheduler`` has been deprecated. Replace uses of it with
``buildbot.schedulers.base.ReconfigurableBaseScheduler``.

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.

Data API
========

The multiline string type of ``ResourceType.eventPathPatterns`` and ``Enpoint.pathPatterns``
attribute has been deprecated. Use list of strings type instead.