From 13d004ac073f4976c3ff1043f917e23f8fe06f10 Mon Sep 17 00:00:00 2001
From: Seth K <44306652+sethkaz@users.noreply.github.com>
Date: Wed, 19 Jul 2023 16:36:12 -0700
Subject: [PATCH] Add github actions readme with first pass info.

---
 docs/GITHUB-ACTIONS-README.md | 72 +++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 docs/GITHUB-ACTIONS-README.md

diff --git a/docs/GITHUB-ACTIONS-README.md b/docs/GITHUB-ACTIONS-README.md
new file mode 100644
index 00000000..0ec7a146
--- /dev/null
+++ b/docs/GITHUB-ACTIONS-README.md
@@ -0,0 +1,72 @@
+# Guide for using KiBot with Github Actions.
+
+This is a guide for getting started using KiBOT with Github Actions
+
+## Basics
+
+[Github Actions](https://github.com/actions) is a CI system that runs on Github. It uses [YAML files](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html) to define what actions it will take. Unfortunately, some of those actions are a bit cryptic.  This guide will try to shed light on those cyptic portions.
+
+
+
+### Basic github file
+
+Must be located at `{repo root}/.github/workflows/{meaningful_name}.yml
+```yaml
+name: KiBot_GitHub_Actions  # Can be any name
+on: [push, pull_request]    # github triggers for running this.
+jobs:   # List of jobs to be run.  Can be used to better organize steps.
+  KiBot-Generation:  # Can be any name
+    runs-on: ubuntu-latest  # Don't change
+    container: ghcr.io/inti-cmnb/kicad7_auto:latest  # Don't Change, except if needing older version of KiCAD.
+
+    steps:  
+    - name: Checkout repo
+      uses: actions/checkout@v3  # Github built-in repo checkout step.
+
+    # Start of the KiBot steps
+    - name: Run KiBot
+      run: |
+        kibot -e "project_name.kicad_sch"
+```
+
+
+### Basic KiBOT file
+This file will match the syntax and keywords described in the [readme](../README.md). 
+```yaml
+kibot:
+  version: 1
+
+preflight:
+  run_erc: true
+  run_drc: true
+  check_zone_fills: true
+
+outputs:
+  - name: 'Print Schema as PDF'
+    comment: "Print schematic (PDF)"
+    type: pdf_sch_print
+    dir: schematics
+    options:
+      output: '%p-Schematic.%x'
+```
+
+## Github-specific details
+
+The `uses: actions/checkout` refers to a specific repo, [Github Actions](https://github.com/actions). 
+
+## KiBot Specific details
+
+
+
+## Caveats, Gotchyas, and Pitfalls
+
+1. KiBot requires a `*.kibot.yaml` file name scheme.  While most places use `*.yml` and `*.yaml` interchangeably, it is specific here. This is especially odd since github uses `*.yml` and kibot uses `*.yaml`
+
+## Different ways of doing things
+
+This section will try to describe some different options for doing things within KiBot and Github, and hope to explain pros and cons.
+
+TODO: Fill this out.
+TODO: (Topic) github artifacts vs exports commited.
+TODO: (Topic) When to run KiBOT??  ERC/DRC only vs full outputs.
+