From 607bee7f42dc59974676039903d2d6dfea22485c Mon Sep 17 00:00:00 2001
From: Christoph Wurst <christoph@winzerhof-wurst.at>
Date: Thu, 8 Oct 2020 16:00:04 +0200
Subject: [PATCH] Document CI and static analysis for apps

Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>
---
 .../digging_deeper/continuous_integration.rst | 95 +++++++++++++++++++
 developer_manual/digging_deeper/index.rst     |  1 +
 2 files changed, 96 insertions(+)
 create mode 100644 developer_manual/digging_deeper/continuous_integration.rst

diff --git a/developer_manual/digging_deeper/continuous_integration.rst b/developer_manual/digging_deeper/continuous_integration.rst
new file mode 100644
index 000000000..8c10ba622
--- /dev/null
+++ b/developer_manual/digging_deeper/continuous_integration.rst
@@ -0,0 +1,95 @@
+======================
+Continuous Integration
+======================
+
+.. sectionauthor:: Christoph Wurst <christoph@winzerhof-wurst.at>
+
+We highly recommend setting up automated tests for your app, so that every change has to pass a defined procedure before it's accepted into the main branch of your repository. Continuous integration typically includes
+
+* Linting: check the syntax of source files, e.g. of all php scripts
+* Static analysis: have tools check the types in your app for type soundness, mostly used for php
+* Unit testing: run unit tests for front-end and back-end where individual classes and components are tested in isolation
+* Integration testing: test components when they are combined
+
+
+Static analysis
+---------------
+
+`Psalm`_ is a static analysis tool that can check if your app code uses all types correctly, like if classes and methods exist. For the basic setup see the `Psalm`_ website. In order to let Psalm know about Nextcloud interfaces (the OCP namespace), you can install the `API package <https://packagist.org/packages/christophwurst/nextcloud>`_. Afterwards you'll be able to check the app with the following ``psalm.xml`` that should be put into the root of the app.
+
+.. code-block:: xml
+
+    <?xml version="1.0"?>
+    <psalm
+        totallyTyped="true"
+        errorLevel="5"
+        resolveFromConfigFile="true"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns="https://getpsalm.org/schema/config"
+        xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
+        errorBaseline="tests/psalm-baseline.xml"
+    >
+        <projectFiles>
+            <directory name="lib" />
+            <ignoreFiles>
+                <directory name="vendor" />
+                <directory name="lib/Vendor" />
+            </ignoreFiles>
+        </projectFiles>
+        <extraFiles>
+            <directory name="vendor" />
+            <ignoreFiles>
+                <directory name="vendor/phpunit/php-code-coverage" />
+            </ignoreFiles>
+        </extraFiles>
+        <issueHandlers>
+            <UndefinedClass>
+                <errorLevel type="suppress">
+                    <referencedClass name="OC" />
+                </errorLevel>
+            </UndefinedClass>
+            <UndefinedDocblockClass>
+                <errorLevel type="suppress">
+                    <referencedClass name="Doctrine\DBAL\Schema\Schema" />
+                    <referencedClass name="Doctrine\DBAL\Schema\SchemaException" />
+                    <referencedClass name="Doctrine\DBAL\Driver\Statement" />
+                    <referencedClass name="Doctrine\DBAL\Schema\Table" />
+                </errorLevel>
+            </UndefinedDocblockClass>
+        </issueHandlers>
+    </psalm>
+
+.. Note:: The definition supresses usages of the global and static class ``OC`` like ``\OC::$server``, which is discouraged but still found in some apps. The doctrine supression is currently necessary as the database mappers and schema abstractions leak some of the 3rd party libraries of Nextcloud that are not known to Psalm.
+
+
+You can put this process into a Github Action that is run for every pull request.
+
+.. code-block:: yaml
+
+    name: Static analysis
+    on: [push]
+    jobs:
+    static-psalm-analysis:
+        runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                ocp-version: [ 'dev-master', 'v20.0.0' ]
+        name: Nextcloud ${{ matrix.ocp-version }}
+        steps:
+            - name: Checkout
+                uses: actions/checkout@master
+            - name: Set up php
+                uses: shivammathur/setup-php@master
+                with:
+                    php-version: 7.4
+                    coverage: none
+            - name: Install dependencies
+                run: composer i
+            - name: Install dependencies
+                run: composer require --dev christophwurst/nextcloud:${{ matrix.ocp-version }}
+            - name: Run coding standards check
+                run: composer run psalm
+
+This creates a matrix, where the app is tested against ``dev-master``, the latest version of ``OCP`` found in the main branch of Nextcloud server, as well as ``v20.0.0``, the currently latest stable release. Adjust this to your needs.
+
+.. _Psalm: https://psalm.dev/docs/
diff --git a/developer_manual/digging_deeper/index.rst b/developer_manual/digging_deeper/index.rst
index ed5890982..384cffa9d 100644
--- a/developer_manual/digging_deeper/index.rst
+++ b/developer_manual/digging_deeper/index.rst
@@ -9,6 +9,7 @@ Digging deeper
    changelog
    debugging
    classloader
+   continuous_integration
    flow
    javascript-apis
    npm