Move CI and documentation from GitLab to GitHub

.documentation/_config.yml

@@ -22,7 +22,7 @@ bibtex_bibfiles:
 
 # Information about where the book exists on the web
 repository:
-  url: https://gitlab.pam-retd.fr/thermosysproandco/ThermoSysPro  # Online location of your book
+  url: https://github.com/EDF-Lab/ThermoSysPro  # Online location of your book
   path_to_book: .documentation  # Optional path to your book, relative to the repository root
   branch: master  # Which branch of the repository should be used when creating links (optional)
 

.gitlab/issue_templates/Default.md → .github/ISSUE_TEMPLATE/default.md

@@ -1,4 +1,10 @@
-<!-- Please use a template. Appropriate labels can also be added, for more information please see [ThermoSysPro gitflow](https://gitlab.pam-retd.fr/thermosysproandco/ThermoSysPro/-/blob/master/ContributionsWorkflow.md?ref_type=heads). -->
+---
+name: Issue
+about: Report a bug or ask a question
+labels: []
+---
+
+<!-- Appropriate labels can also be added, for more information please see [ThermoSysPro workflow](https://github.com/EDF-Lab/ThermoSysPro/blob/master/ContributionsWorkflow.md). -->
 
 # Issue
 

.gitlab/issue_templates/Enhancement.md → .github/ISSUE_TEMPLATE/enhancement.md

@@ -1,3 +1,9 @@
+---
+name: Change request
+about: Propose a new feature or an improvement
+labels: [enhancement]
+---
+
 # Change Request
 
 ## Description

.github/workflows/documentation.yml

@@ -0,0 +1,91 @@
+# Generate Markdown from the Modelica annotations of ThermoSysPro
+# (.documentation/mo_to_book.py), build the Jupyter Book, and deploy it to
+# GitHub Pages.
+#
+#   - Push to master, or manual run on master: the book is built and deployed.
+#   - Pull request: the book is built and, TEMPORARILY (while this workflow is
+#     being developed), also deployed, replacing the master documentation
+#     until the next deployment. Pull requests from forks are not deployed
+#     (no write access).
+#     TODO: once the workflow is validated, deploy master only: change the two
+#     DEPLOY conditions below, and restrict again the deployment branches of
+#     the github-pages environment to master.
+#
+# Required repository settings:
+#   - Settings > Pages > Build and deployment > Source: GitHub Actions.
+#   - TODO temporary, while pull requests are deployed: Settings > Environments
+#     > github-pages > Deployment branches and tags: allow all branches (by
+#     default only the default branch can deploy, and pull requests are
+#     rejected).
+#   - variable OPENMODELICA_IMAGE (optional): OpenModelica Docker image.
+
+name: Documentation
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master, develop]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ vars.OPENMODELICA_IMAGE || 'openmodelica/openmodelica:v1.26.7-ompython' }}
+    steps:
+      # python3-venv is used to avoid installing Python packages as root.
+      - name: Install system dependencies
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends git ca-certificates python3-venv
+
+      - name: Checkout ThermoSysPro
+        uses: actions/checkout@v4
+
+      # Docker jobs run as root. OpenModelica refuses to start its ZMQ server
+      # as root, and omc4py needs that server, so the documentation is
+      # generated as ciuser.
+      - name: Install Python dependencies
+        run: |
+          useradd --create-home --shell /bin/bash ciuser
+          chown -R ciuser:ciuser "$GITHUB_WORKSPACE"
+          su ciuser -c "python3 -m venv ~/venv && . ~/venv/bin/activate && python -m pip install --upgrade pip && python -m pip install -r '$GITHUB_WORKSPACE/.documentation/requirements.txt'"
+
+      # Fail early, with a clear message, if the library cannot be loaded.
+      - name: Check that OpenModelica loads ThermoSysPro
+        run: |
+          omc --version
+          su ciuser -c ". ~/venv/bin/activate && cd '$GITHUB_WORKSPACE' && python3 -c 'import omc4py; omc = omc4py.open_session(); print(omc.getVersion()); assert omc.loadFile(\"ThermoSysPro/package.mo\"); print(\"Loaded ThermoSysPro with\", len(omc.getClassNames(\"ThermoSysPro\")), \"top-level classes\"); omc.close()'"
+
+      - name: Build the book
+        run: su ciuser -c ". ~/venv/bin/activate && cd '$GITHUB_WORKSPACE/.documentation' && python3 mo_to_book.py && jupyter-book build ."
+
+      - name: Upload GitHub Pages artifact
+        if: github.event.pull_request.head.repo.full_name == github.repository || github.ref == 'refs/heads/master'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: .documentation/_build/html
+
+  deploy:
+    needs: build
+    # DEPLOY condition. Once validated, deploy master only:
+    if: github.ref == 'refs/heads/master'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/openmodelica-tests.yml

@@ -0,0 +1,147 @@
+# Test with OpenModelica the Examples models of ThermoSysPro, using
+# ModelicaTests (https://gitlab.pam-retd.fr/thermosysproandco/modelicatests),
+# and compare them with a reference version of ThermoSysPro:
+#   - .test/config_new_openmodelica.json tests the checked out version,
+#   - .test/config_ref_openmodelica.json tests the reference, cloned by
+#     ModelicaTests from this repository.
+# The reference is the target branch of the pull request (develop, or master
+# for hotfix/misc branches). On a push to develop or a manual run, the reference
+# is master. On a push to master, the checked out version is tested alone.
+# If the reference cannot be tested, the checked out version is tested alone.
+# The run summary, written by .test/report.py, shows the results table of the
+# ModelicaTests HTML report for the tested version, and the comparison with the
+# reference (fixed, regression, results changed).
+#
+# Required repository settings (Settings > Secrets and variables > Actions):
+#   - secret MODELICATESTS_TOKEN: GitLab token with read_repository access to
+#     the ModelicaTests project.
+#   - variable OPENMODELICA_IMAGE (optional): OpenModelica Docker image, which
+#     must provide the Modelica Standard Library 4.0.0.
+#
+# The Dymola tests run on an internal GitLab runner (see .gitlab-ci.yml).
+#
+# Failing models do not fail the workflow: they are reported in the run
+# summary, and in the uploaded HTML/CSV reports and OpenModelica logs. The
+# workflow only fails on infrastructure errors (library or MSL not loadable,
+# ModelicaTests crash).
+
+name: OpenModelica tests
+
+on:
+  push:
+    branches: [master, develop]
+  pull_request:
+    branches: [master, develop]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test-openmodelica:
+    # Pull requests from forks have no access to secrets, so the private
+    # ModelicaTests repository cannot be cloned: skip the job instead of failing.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ vars.OPENMODELICA_IMAGE || 'openmodelica/openmodelica:v1.26.7-ompython' }}
+    env:
+      REF_BRANCH: ${{ github.base_ref || 'master' }}
+      # Empty when the checked out version is master itself: nothing to compare.
+      RUN_REF: ${{ (github.event_name == 'pull_request' || github.ref_name != 'master') && 'true' || '' }}
+    steps:
+      # git is needed to clone ModelicaTests; python3-venv is used to avoid
+      # installing Python packages as root.
+      - name: Install system dependencies
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends git ca-certificates python3-venv
+
+      # Checked out at the workspace root, as in the GitLab pipeline: the
+      # library is then found at ../../ThermoSysPro/package.mo from
+      # modelicatests/tests.
+      - name: Checkout ThermoSysPro
+        uses: actions/checkout@v4
+
+      - name: Clone ModelicaTests
+        env:
+          MODELICATESTS_TOKEN: ${{ secrets.MODELICATESTS_TOKEN }}
+        run: git clone --depth 1 "https://oauth2:${MODELICATESTS_TOKEN}@gitlab.pam-retd.fr/thermosysproandco/modelicatests.git" modelicatests
+
+      # Copy ThermoSysPro test configuration files into the ModelicaTests test
+      # directory, where the runner expects them, and point the reference to
+      # the reference branch of this repository.
+      - name: Configure ModelicaTests
+        env:
+          REF_URL: ${{ github.server_url }}/${{ github.repository }}.git
+        run: |
+          cp .test/*.json modelicatests/tests/
+          cat > modelicatests/tests/local_config.json <<'JSON'
+          {
+            "dymola": {
+              "egg": "",
+              "exe": ""
+            },
+            "openmodelica": {
+              "exe": "/usr/bin/omc"
+            }
+          }
+          JSON
+          python3 - <<'PY'
+          import json, os
+          file = "modelicatests/tests/config_ref_openmodelica.json"
+          with open(file) as f:
+              config = json.load(f)
+          config["libs"]["ThermoSysPro"]["path"].update(url=os.environ["REF_URL"], target=os.environ["REF_BRANCH"])
+          with open(file, "w") as f:
+              json.dump(config, f, indent=4)
+          PY
+          if [ -n "$RUN_REF" ]; then echo "Reference: $REF_URL ($REF_BRANCH)"; else echo "No reference: master tested alone"; fi
+
+      # Docker jobs run as root. OpenModelica refuses to start its ZMQ server
+      # as root, and omc4py needs that server, so the tests run as ciuser.
+      # If the run with the reference fails, its outputs are removed and the
+      # checked out version is tested alone (report.py then skips the comparison).
+      - name: Run ModelicaTests
+        run: |
+          useradd --create-home --shell /bin/bash ciuser
+          chown -R ciuser:ciuser "$GITHUB_WORKSPACE"
+          su ciuser -c "cd '$GITHUB_WORKSPACE/modelicatests' && python3 -m venv .venv && . .venv/bin/activate && python -m pip install --upgrade pip && python -m pip install ."
+          cd modelicatests/tests
+          if [ -z "$RUN_REF" ]; then
+            su ciuser -c ". ../.venv/bin/activate && python3 run_cli.py config_new_openmodelica.json --ncpus 4 --timeout 120"
+          else
+            su ciuser -c ". ../.venv/bin/activate && python3 run_cli.py config_ref_openmodelica.json config_new_openmodelica.json --ncpus 4 --timeout 120" || {
+              echo "::warning::ModelicaTests failed with the reference ($REF_BRANCH), see the log above: testing the checked out version alone."
+              rm -rf config_ref_openmodelica.csv config_ref_openmodelica.html config_ref_openmodelica-* TMP_*
+              su ciuser -c ". ../.venv/bin/activate && python3 run_cli.py config_new_openmodelica.json --ncpus 4 --timeout 120"
+            }
+          fi
+
+      # Written to a file first: ciuser cannot write to $GITHUB_STEP_SUMMARY.
+      - name: Write results summary
+        if: always()
+        run: |
+          su ciuser -c "cd '$GITHUB_WORKSPACE/modelicatests/tests' && . ../.venv/bin/activate && python3 '$GITHUB_WORKSPACE/.test/report.py' config_ref_openmodelica.csv config_new_openmodelica.csv > report.md"
+          cat modelicatests/tests/report.md >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: modelicatests-report
+          retention-days: 7
+          # TMP_*/<model>/ holds the OpenModelica check, build and simulation
+          # logs of each model, needed to understand a failure.
+          path: |
+            modelicatests/tests/*.csv
+            modelicatests/tests/*.html
+            modelicatests/tests/*-junit.xml
+            modelicatests/tests/report.md
+            modelicatests/tests/TMP_*/*/*.log
+            modelicatests/tests/TMP_*/*/*.txt
+          if-no-files-found: warn

.gitignore

@@ -17,3 +17,8 @@ status*
 *.c
 buildlog.txt
 *.bak-mo
+
+# Files generated by .documentation/mo_to_book.py and jupyter-book
+.documentation/_build/
+.documentation/_toc.yml
+.documentation/modelica_docs/