.. _create-cli:


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 :ref:`create`) 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``:

.. code-block:: 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``:

.. code-block:: none

    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:

.. code-block:: bash

   $> 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:

.. code-block:: json

    {
        "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.