Add-on-template/README.md

# AllSpice Actions Add-on template

This Add-on shows you how to create an Add-on, and how to set up the files to make an API to pass inputs to the Add-on.

## Table of Contents

  - [Usage](#usage)
  - [Inputs](#inputs)
  - [Outputs](#outputs)
  - [Example Workflow](#example-workflow)
  - [License](#license)

## Usage

![Diagram of Add-on files and how they link together. A visual representaiton of this page](images/add-on-diagram.png)

### Calling this add-on
This Add-on can be called from an external repository workflow file.
There is an example workflow file in this repository:
[.allspice/workflows/add-on-workflow-example.yml](.allspice/workflows/add-on-workflow-example.yml)

You can copy this workflow file to another repository and use it to call this Add-on template.

### Define API in action.yml
The file [action.yml](action.yml) describes how to connect your workflow call of the add-on to the actual script and specifies how parameters are used.

This is considered an API contract.

Below is the `action.yml` file for this repo. You can see that the `inputs` section maps inputs to input variables.

The second section composes the args from inputs and other values and passes it to the Dockerfile.
```yaml
name: "Hardware DevOps Action"
description: >
  A generic AllSpice Action Add-on for hardware development tasks such as schematic review,
  PCB review, ECO review, and release. This action demonstrates defining parameters 
  for these tasks and utilizing GitHub context information.

inputs:
  source_file:
    description: >
      Path to the source file or directory from the root of the repo. For example,
      the path to a schematic or PCB file.
    required: true
  output_file_name:
    description: "Name of the output file"
    required: true
    default: "output.txt"
  config_file:
    description: >
      Path to a configuration file for the task.
    required: true
  task_type:
    description: >
      The type of hardware task to perform. Options include 'Schematic-Review', 
      'PCB-Review', 'ECO-Review', 'Release'.
    default: "Schematic-Review"
  additional_params:
    description: >
      Any additional parameters required for the task, provided as a JSON string.
    default: "{}"

runs:
  using: "docker"
  image: "Dockerfile"
  args:
    - "--source_file"
    - "${{ inputs.source_file}}"
    - "--output_file"
    - "${{ github.workspace}}/${{ inputs.output_file_name }}"
    - "--config_file"
    - ${{ inputs.config_file }}
    - "--task_type"
    - ${{ inputs.task_type }}
    - "--additional_params"
    - ${{ inputs.additional_params }}
    - "--source_ref"
    - ${{ allspice.sha }}
    - "--server_url"
    - ${{ allspice.server_url }}
    - "--allspice_token"
    - ${{ secrets.ALLSPICE_TOKEN }}
env:
  GITHUB_TOKEN: ${{ github.token }}
```

### Define Add-on script (entrypoint.py)

[`entrypoint.py`](entrypoint.py)
This is the program that you will use to perform your Add-on. In this case, we use Python and the py-allspice API wrapper.

The first part of the program is parsing the arguments from the API contract, and the second part runs your actual Add-on. In this template example the Python script performs a connection test to AllSpice, and displays the parameters passed from the calling Workflow file.

### Define Dockerfile

`Dockerfile`
The Dockerfile specifies how to set up the environment and what file to run as the Add-on script.

In this repo template, we load Python 3.12, install modules from requirements.py, and thn run entrypoint.py.

```Dockerfile
FROM python:3.12-bookworm

COPY requirements.txt /requirements.txt
COPY entrypoint.py /entrypoint.py

RUN pip install -r /requirements.txt

ENTRYPOINT [ "/entrypoint.py" ]
```

### requirements.txt

The requirements.txt file specifies which Python modules to load and which version to load.

module-name=version#

`py-allspice` AllSpice’s native Python wrapper to the AllSpice API.

`pyyaml` A YAML markdown language processor. Helps parse workflow.yml files.

```
py-allspice==3.3.0
pyyaml~=6.0
```

### Testing files

This repo has an optional Action workflow that checks the syntax of entrypoint.py. This is helpful because Python is an interpreted language.

You do not need these files to run your Add-on, however using tests will help you spot errors.

- `.allspice/dependabot.yml` - Instructions for repository workflow tests.
- `.allspice/workflows/test.yml` - Workflow to test this repo on design review.
  - Lints 3 different versions of python (Checks syntax)
- `pyproject.toml` - Linter setup. Specifies how the repository workflow tests will check the syntax of this repository
- `requirements-test.txt` - the requirements for the test workflow.


## Add-on input API
You can customize your Add-on inputs to match your own workflow. These are some example inputs that are helpful for running Add-ons.

You can have as many or as few inputs as you need for your workflow.

- `source_file`: The path to the source file used for the task. Example: `Archimajor.PrjPcb`, `Schematics/Beagleplay.dsn`.
- `task_type`: The type of hardware task to perform. Options include `Schematic-Review`, `PCB-Review`, `ECO-Review`, `Release`. (default: `Schematic-Review`)
- `source_ref`: The git reference the task should be performed for (e.g., branch name, tag name, commit SHA). (default: `main`)
- `server_url`: The URL of your AllSpice server instance.
- `output_file`: The path to the output file. If absent, the output will be printed to the command line.
- `additional_params`: Any additional parameters required for the task, provided as a JSON string. (default: `{}`)
- `allspice_token`: Your AllSpice application token. Generate a token at: https://hub.allspice.io/user/settings/applications
- `config_file`: Path to the config file.
- `input_file`: Path to the input file.

## Outputs

The outputs are dependent on the task performed and will be printed to the command line or saved to the specified `output_file`.

In this template repo, there are no actual outputs, however the name of the output is displayed to demnostrate the correct passing of inputs to the script.

## Example Workflow

Here is the file [./allspice/workflows/add-on-workflow-example.yml](./allspice/workflows/add-on-workflow-example.yml)

This shows how to call the Add-on in this repo.

```yaml
name: Example AllSpice Add-on Template

on: [push, pull_request]

jobs:
  hardware-devops:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run Hardware DevOps Action
        uses: https://hub.allspice.io/AllSpice-Demos/Add-on-template@v0.1
        with:
          source_path: ".allspice/examples/input.txt"
          output_file_name: "output.txt"
          config_file: ".allspice/examples/config.yml"
          task_type: "Schematic-Review"
          additional_params: '{"SCH_VER":"3"}'
        env:
          ALLSPICE_TOKEN: ${{ allspice.token }}
```