From 0a295297312ea41051a2ff48b5683e42177ff2d4 Mon Sep 17 00:00:00 2001
From: Ganesh Gore <goreganesh007@gmail.com>
Date: Tue, 26 Jan 2021 16:26:43 -0700
Subject: [PATCH] [Docs] Added CI/CD docs

---
 docs/source/dev_manual/ci_cd_setup/index.rst | 108 +++++++++++++++++++
 docs/source/dev_manual/index.rst             |   5 +
 docs/source/index.rst                        |   6 ++
 3 files changed, 119 insertions(+)
 create mode 100644 docs/source/dev_manual/ci_cd_setup/index.rst
 create mode 100644 docs/source/dev_manual/index.rst

diff --git a/docs/source/dev_manual/ci_cd_setup/index.rst b/docs/source/dev_manual/ci_cd_setup/index.rst
new file mode 100644
index 000000000..6d213c0ad
--- /dev/null
+++ b/docs/source/dev_manual/ci_cd_setup/index.rst
@@ -0,0 +1,108 @@
+
+CI/CD setup
+------------
+
+OpenFPGA implements CI/CD system using Github actions.
+The following figure shows the Actions implements flow.
+The source building is skipped if there are changes only in ``openfpga_flow`` or ``docs`` directory,
+in which case the docker image compiled for the latest master branch is used for running a regression.
+
+
+.. graphviz::
+   :align: center
+
+   digraph G {
+       node [fontname = "Handlee"];
+       edge [fontname = "Handlee"];
+       Trigger [
+           label = "Action triggered"
+       ];
+
+       masterCompare [
+           label = "Diff with current master"
+       ];
+
+       Build [
+           label = "Changes only in\n openfpga_flow/doc?"
+           shape = diamond
+       ];
+
+       BuildDocker [
+           label = "Run build regression test\nBuild docker images"
+           shape = box
+       ];
+
+       PushDockersCond [
+           label = "Is merge\non master?"
+           shape = diamond
+       ];
+
+       PushDockers [
+           label = "Push docker Images\n(maintain compiled binary\nin docker + Example tasks)"
+           shape = box
+       ];
+
+       RunRegression [
+           label = "Run functional regeression test"
+           shape = box
+       ];
+
+     Trigger ->masterCompare;
+     masterCompare ->Build;
+     Build -> BuildDocker [ label = "No" ];
+     BuildDocker -> PushDockersCond;
+     edge[weight=0.5] Build -> RunRegression [ label = "Yes" ];
+     edge[weight=10] PushDockersCond -> RunRegression [ label = "No" ];
+     PushDockersCond -> PushDockers [ label = "Yes" ];
+     edge[weight=2] PushDockers -> RunRegression;
+
+     {
+       rank=same;
+       PushDockersCond PushDockers;
+     };
+   }
+
+
+|
+
+
+.. option:: Build regression test
+
+    The OpenFPGA soure is compiled with the following set of compilers.
+
+      #. gcc-5
+      #. gcc-6
+      #. gcc-7
+      #. gcc-8
+      #. gcc-9
+      #. clang-6.0
+      #. clang-8
+
+    The docker images for these build enviroment are available on `github packages <https://github.com/orgs/lnis-uofu/packages>`_.
+
+.. option:: Functional regeression test
+
+    OpenFPGA maintains a set of functional tests to validate the different functionality.
+    The test are broadly catagories into ``basic_reg_test``, ``fpga_verilog_reg_test``,
+    ``fpga_bitstream_reg_test``, ``fpga_sdc_reg_test``, and ``fpga_spice_reg_test``.
+    A functional regression test is run for every commit on every branch.
+
+
+How to debug failed regression test
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In case the ``funtional regression test`` fails,
+the actions script will collect all ``.log`` files from
+the task directory and upload as a artifacts on github storage.
+These artifacts can be downloaded from the github website actions tab, for more reference follow `this <https://docs.github.com/en/actions/managing-workflow-runs/downloading-workflow-artifacts>`_ article.
+
+**NOTE** : The retention time of these artifacts is 1 day,
+so in case user want to reserve the failure log for longer duration back it up locally
+
+Release Docker Images
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. option:: ghcr.io/lnis-uofu/openfpga-master:latest
+
+    This is a bleeding-edge release from the current master branch of OpenFPGA.
+    It is updated automatically whenever there is activity on the master branch.
+    Due to high development activity, we recommend the user to use the bleeding-edge version to get access to all new features and report an issue in case there are any bugs.
\ No newline at end of file
diff --git a/docs/source/dev_manual/index.rst b/docs/source/dev_manual/index.rst
new file mode 100644
index 000000000..c728d39b7
--- /dev/null
+++ b/docs/source/dev_manual/index.rst
@@ -0,0 +1,5 @@
+
+.. toctree::
+   :maxdepth: 1
+
+   ci_cd_setup/index
diff --git a/docs/source/index.rst b/docs/source/index.rst
index f507a8c54..df991919f 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -24,6 +24,12 @@ Welcome to OpenFPGA's documentation!
 
    manual/index
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Developers Manual
+
+   dev_manual/index
+
 .. toctree::
    :maxdepth: 2
    :caption: Appendix