RFD4 - Testing Farm Errors

Status: 💡 planned

This RFD introduces a naming scheme for common user facing errors in the Testing Farm service and describes its intended usage.

Introduction

Testing Farm is a complex service consisting of multiple components and has a significant user base. To improve the user experience and enable users to handle some error conditions themselves, we are introducing Testing Farm Error codes. These will be well-documented, common errors that users may encounter, providing hints on how to investigate the issues they face from Testing Farm and what they should try first before reaching out to us. These error codes will be documented on our documentation page and will be easily linkable via a friendly URL. Our components should start exposing these error codes gradually.

Error Code Structure

The error code will have this structure:

TFE-<ERROR_CODE>

The error MUST start with the TFE- prefix. TFE stands for Testing Farm Error.

The error code ID is a number, i.e., 1.

Examples:

TFE-1
TFE-99

Documentation

Each error will be documented in Testing Farm documentation. All errors will have their own page.

Tags

The errors will use Asciidoctor custom document attribute tags in each document to categorize the error.

The tags will be placed at the beginning of the document:

:tags: api

This RFD will be updated in case new tags are added.

Only tags defined in this document can be used in the tags attribute.

Multiple tags can be specified, delimited with a comma, e.g. :tags: api, worker.

Components

Tags related to specific Testing Farm component

api
cli
dispatcher
provisioner
server
ui
worker

Status

Status of the error. The lifetime of the errors can be limited due to improvements and fixes in the service. Errors are kept for historical purposes, and we will never remove them.

active        # actively used error
resolved      # error had been fixed, and you should not see it anymore
deprecated    # error had been deprecated and replaced with a different error

Error URLs

We will be introducing a new subdomain errors.testing.farm linking to the error’s documentation. Each error will be accessible via an easily constructable URL, e.g. https://errors.testing.farm/TFE-1.