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.