Create an issue (CLI)

Publishing an issue on the Errata Service through the CLI, you must first edit an issue template. The issue template is composed of:

• a .json file including several attributes or fields that will interact with the validation process,

• a .txt file gathering the identifiers of the affected datasets.

Requirements

Indeed requirements to create an issue (see Create an issue) are enforced by a JSON validation. These JSON attributes/fields consist in:

Field	Requirement
uid	Not expected and generated by the server
title	Mandatory (between 16 and 255 characters)
description	Mandatory (between 16 and 1023 characters)
project	Mandatory and value-controlled
severity	Mandatory and value-controlled
status	Not expected and new generated by the client
landing_page	Optional
materials	Optional
dateCreated	Not expected and generated by the client
dateUpdated	Not expected and generated by the client
dateClosed	Not expected

Warning: Safeguards requirements are:

• The issue identifier is automatically generated on issue creation and is assigned to the issue throughout its life cycle.

• Empty attributes are not allowed.

• A precise and concise issue description that must make sense for end users (not just “wrong data”) is highly recommended.

• The landing page is expected to be a valid URL (it is checked upon validation).

• The materials are expected to be a list of valid URL of files (only image format are allowed, url also checked upon validation).

• All optional URLs must be valid (i.e., accessible).

• A status “new” will be generated by the server on the creation.

• The creation date is also generated by the server.

Note: the accepted terms for issue severity are:

• “low”The issue concerns file management (e.g., addition, removal, period extension, etc.),

• “medium”The issue concerns metadata (NetCDF attributes) without undermining the values of the involved variable,

• “high”The issue concerns single point variable or axis values,

• “critical”The issue concerns the variable or axis values undermining the analysis. The use of this data is strongly discouraged.

You must then list all the affected dataset IDs in a .txt file. A dataset ID is a sequence of dot-separated facets that follows the Data Reference Syntax of the corresponding project. The dataset identifiers has to append the dataset version number.

Warning: if one of the dataset ID is malformed or if the dataset list is empty, the command will raise an exception and exit, users should correct the malformed dataset ID (which will be indicated in the error message).

Edit the issue

Here is concrete example of what an issue declaration through the ESGF issue client should look like. On declaration of the issue this is the regular form of an issue:

issue.json:

{
    "title": "Test issue title",
    "description": "This is a test description, void of meaning.",
    "project": "cmip6",
    "severity": "medium",
    "materials": [
        "http://myerrata.com/images/before.jpg",
        "http://myerrata.com/images/after.jpg"
    ],
    "url": "http://websitetest.com/",
}

dataset.txt:

cmip6.CMIP.IPSL.IPSL-CM6-1.historical.r1i1p1f1.3hr.clt.gr.v20170531
cmip6.CMIP.IPSL.IPSL-CM6-1.historical.r1i1p1f1.Amon.tas.gr.v20170531
[...]

Register the issue

After having successfully formatted the both files in the indicated fashion, create your issue using the create subcommand:

$> esgissue create --issue /path/to/issue.json --dsets /path/to/datasets.txt

On success the local issue file will be modified and the client returns you the URL of the newly registered issue on the Errata Service front-end. The creation and update dates will be appended as well as the issue UID and status:

{
    "uid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "title": "Test issue title",
    "description": "This is a test description, void of meaning.",
    "project": "cmip6",
    "severity": "medium",
    "materials": [
        "http://errata.ipsl.upmc.fr/static/images_errata/time.jpg",
        "http://errata.ipsl.upmc.fr/static/images_errata/time5.jpg"
    ],
    "url": "http://websitetest.com/",
    "status": "new",
    "dateClosed": "YYYY-MM-DD HH:MM:SS",
    "dateUpdated": "YYYY-MM-DD HH:MM:SS"
}

Note: make sure the client has sufficient writing rights to the file. It updates local files.