.. _Maintenance:

🔨 Maintenance
==============

Single source of truth
----------------------

The source for all colours are stored in the Photoshop File ``colours.psd``.  
This is the **single source of truth** and all assets origin from this file.

Constraints
-----------

You can define a new colour family space based on the existing colour families.  

Please note you've to follow these constraints:

1. Open the ``colours.psd`` file in Adobe Photoshop in **Lab Color** mode
2. Use the **grey** family as base and add a colour overlay with the **layer mode «Color»**
3. Ensure that the colours match the `WCAG guidelines <https://www.w3.org/TR/WCAG21/>`_ for normal text (in black and white), e.g. via `Color.review <https://color.review/>`_

Builder workflow
----------------

There's a **Python builder** called ``cicd-builder`` which can be used to create most CI/CD assets.
However, for the CLR file there's a **CLR converter** called ``json2clr``, which creates a CLR file from the JSON asset.

The workflow to build the assets looks like this:

.. uml::

    @startuml

    actor user

    file photoshop as "**Photoshop File**\ncolours.psd"
    file png as "**Image**\ncolours.png"
    file names as "**Names**\ncolours.txt"

    component builder as "**Builder**\ncicd-builder"

    package assets as "Assets" {
        artifact rest as "**reST file**\n\nSphinx colours\ndocumentation."
        artifact svg as "**SVG file**\n\nA vector image."
        artifact json as "**JSON file**\n\nAll colours in a\ncomputable format."
        artifact text as "**Text Files**\n\nRGB values in\ndec & hex."
        artifact ase as "**ASE file**\n\nAdobe's Swatch\nExchange file."
        artifact clr as "**CLR file**\n\nApple's Colour List\nfile."
    }

    component json2clr as "**CLR converter**\njson2clr"

    user --> photoshop : opens the Photoshop file (SSOT)
    photoshop --> png : exports the PNG file
    png .> builder : fetches colours from PNG
    names ..> builder : fetches names from text file

    builder --> rest : builds reST
    builder --> svg : builds SVG
    builder --> json : builds JSON
    builder --> text : builds TXT
    builder --> ase : builds ASE
    builder -> json2clr : triggers converter
    json ..> json2clr : reads the JSON file
    json2clr --> clr : builds CLR 

    @enduml

Sphinx will then take the built assets of the ``cicd-builder``, as well as the static reST files and creates the CI / CD documentation from it:

.. uml::

    @startuml

    component builder as "**Builder**\ncicd-builder"
    component sphinx as "**Sphinx**\n\nDocumentation builder."

    package files as "Sphinx Files" {
        database assets as "**Assets**\n\nThe dynamic assets built by the cicd-builder.\n"
        database static as "**Static reST files**\n\nThe static reST Sphinx files.\n"
    }

    artifact documentation as "**CI/CD documentation**\n\nThe built and deployed CI/CD documentation."

    builder --> assets : builds assets

    static ..> sphinx : Sphinx reads\nstatic files
    assets ..> sphinx : Sphinx reads\ndynamic files

    sphinx --> documentation : Sphinx builds the documentation

    @enduml

.. important::

    Please note only the ``colours.psd`` & ``colours.png`` files are committed to the repository. The rest of the assets are automatically built by ``cicd-builder`` & ``json2clr`` via GitLab's CI/CD pipeline.

Update colours
--------------

To update the colours, ensure you've read and understand the :ref:`Single source of truth`, :ref:`Constraints` & :ref:`Builder workflow` chapter. If you understand them, you can update the colours like this:

1. Open the ``colours.psd`` in Photoshop and edit the colours
2. Export the new ``colours.png`` from it

This should be enough to :ref:`run the builder <Run builder>` and deploy the new colours.

.. hint::

    If you've new colours or want to change the name, also update the ``colours.txt`` file.

Build documentation
-------------------

Setup environment
~~~~~~~~~~~~~~~~~

To setup the environment, run these commands:

.. code-block:: bash

    make venv
    source .venv/bin/activate
    make develop

Run builder
~~~~~~~~~~~

To most straight-forward way to create the complete documentation with all assets is to run this command:

.. code-block:: bash

    make build

.. hint::
    
    The built documentation can be found in the ``build/docs/`` directory.

If you want to improve the documentation without running the builder manually, you can also run the Sphinx autobuilder by executing this command:

.. code-block:: bash

    make autodocs

.. hint::

    This will only watch & rebuild the Sphinx documentation in the ``docs/`` directory. If you update the ``colours.png`` or want to recreate the assets, run ``make assets`` explicitly.

Compile json2clr
----------------

.. hint::

    Apple's Color List file (aka ``.clr``) is a binary file, containing colours which can be accessed throughout macOS.

    Generating the CLR file with Python is a complicated task, since the file is properitary binary.
    However, in comparison with Python, generating the CLR file with an appropriate API such as in ObjectivC / Swift is a much easier task.

    Thus we've decided to create a properitary converter from our JSON to the CLR file.

To compile the ``json2clr`` binary, you can use the `Swift <https://swift.org/>`_ compiler:

.. code-block:: bash

    cd confirm/ci/json2clr
    swiftc json2clr.swift


Development guidelines
----------------------

Please have a look at our :ref:`guidelines:Guidelines` when contributing to this project.