From 02bfa4213f948b57f76880518296d9435c542652 Mon Sep 17 00:00:00 2001
From: Pierre Smeyers <pierre.smeyers@gmail.com>
Date: Fri, 10 Jun 2022 14:33:28 +0200
Subject: [PATCH] doc: Cobertura report + commented code in template

---
 README.md                      | 65 ++++++++++++++--------------------
 templates/gitlab-ci-python.yml | 21 +++++++++++
 2 files changed, 47 insertions(+), 39 deletions(-)

diff --git a/README.md b/README.md
index 065c057..554e717 100644
--- a/README.md
+++ b/README.md
@@ -83,42 +83,6 @@ The Python template features four alternative test jobs:
 * or `py-nosetest` that performs tests based on [nose](https://nose.readthedocs.io/en/latest/) Python lib,
 * or `py-compile` that performs byte code generation to check syntax if not tests are available.
 
-#### Activate code coverage report artifact
-
-Code coverage report artifact is disabled, due to a [deprecated syntax](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78132).
-
-To activate code coverage report artifact, you need to update python-test step depending on our gitlab version:
-* gitlab < 14.10 :
-```yaml
-artifacts:
-    name: "$CI_JOB_NAME artifacts from $CI_PROJECT_NAME on $CI_COMMIT_REF_SLUG"
-    expire_in: 1 day
-    when: always
-    reports:
-      junit:
-        - $PYTHON_PROJECT_DIR/reports/TEST-*.xml
-      cobertura: $PYTHON_PROJECT_DIR/reports/coverage.xml
-    paths:
-      - $PYTHON_PROJECT_DIR/reports/
-```
-
-* gitlab >= 14.10
-```yaml
-artifacts:
-    name: "$CI_JOB_NAME artifacts from $CI_PROJECT_NAME on $CI_COMMIT_REF_SLUG"
-    expire_in: 1 day
-    when: always
-    reports:
-      junit:
-        - $PYTHON_PROJECT_DIR/reports/TEST-*.xml
-    coverage_report:
-        ​coverage_format: cobertura
-        path: ​$PYTHON_PROJECT_DIR/reports/coverage.xml
-    paths:
-      - $PYTHON_PROJECT_DIR/reports/
-```
-
-
 #### `py-unittest` job
 
 This job is **disabled by default** and performs tests based on [unittest](https://docs.python.org/3/library/unittest.html) Python lib.
@@ -219,6 +183,31 @@ It is bound to the `build` stage, and uses the following variables:
 | --------------------- | ----------------------------------------------------------------------------- | ------------- |
 | `PYTHON_COMPILE_ARGS` | [`compileall` CLI options](https://docs.python.org/3/library/compileall.html) | `*`           |
 
+#### Activate code coverage report artifact
+
+Code coverage report artifact is disabled, due to a [deprecated syntax](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78132).
+
+In order to activate code coverage report artifact, you need to override your actual unit test job depending on our GitLab version.
+
+Here is an example with `py-pytest` job (change to `py-unittest` or `py-nosetests` depending on your unit tests library):
+
+* for GitLab < 14.10:
+```yaml
+py-pytest:
+  artifacts:
+    reports:
+      cobertura: $PYTHON_PROJECT_DIR/reports/coverage.xml
+```
+* for GitLab >= 14.10:
+```yaml
+py-pytest:
+  artifacts:
+    reports:
+      coverage_report:
+        ​coverage_format: cobertura
+        path: ​$PYTHON_PROJECT_DIR/reports/coverage.xml
+```
+
 ### SonarQube analysis
 
 If you're using the SonarQube template to analyse your Python code, here is a sample `sonar-project.properties` file:
@@ -342,8 +331,6 @@ You should disable the `semantic-release` job (as it's the `py-release` job that
 
 Finally, the semantic-release integration can be disabled with the `PYTHON_SEMREL_RELEASE_DISABLED` variable.
 
-####
-
 #### Git authentication
 
 A Python release involves some Git push operations.
@@ -359,7 +346,7 @@ The key should not have a passphrase (see [how to generate a new SSH key pair](h
 Specify :lock: `$GIT_PRIVATE_KEY` as secret project variable with the private part of the deploy key.
 
 ```PEM
------BEGIN OPENSSH PRIVATE KEY-----
+-----BEGIN 0PENSSH PRIVATE KEY-----
 blablabla
 -----END OPENSSH PRIVATE KEY-----
 ```
diff --git a/templates/gitlab-ci-python.yml b/templates/gitlab-ci-python.yml
index a63957e..d101207 100644
--- a/templates/gitlab-ci-python.yml
+++ b/templates/gitlab-ci-python.yml
@@ -653,6 +653,13 @@ py-unittest:
     reports:
       junit:
         - $PYTHON_PROJECT_DIR/reports/TEST-*.xml
+      # declaring the Cobertura report depends on the GitLab version :(
+      # GitLab < 14.10
+      # cobertura: $PYTHON_PROJECT_DIR/reports/coverage.xml
+      # GitLab >= 14.10
+      # coverage_report:
+      #   ​coverage_format: cobertura
+      #   path: ​$PYTHON_PROJECT_DIR/reports/coverage.xml
     paths:
       - $PYTHON_PROJECT_DIR/reports/
   rules:
@@ -676,6 +683,13 @@ py-pytest:
     reports:
       junit:
         - $PYTHON_PROJECT_DIR/reports/TEST-*.xml
+      # declaring the Cobertura report depends on the GitLab version :(
+      # GitLab < 14.10
+      # cobertura: $PYTHON_PROJECT_DIR/reports/coverage.xml
+      # GitLab >= 14.10
+      # coverage_report:
+      #   ​coverage_format: cobertura
+      #   path: ​$PYTHON_PROJECT_DIR/reports/coverage.xml
     paths:
       - $PYTHON_PROJECT_DIR/reports/
   rules:
@@ -698,6 +712,13 @@ py-nosetests:
     reports:
       junit:
         - $PYTHON_PROJECT_DIR/reports/TEST-*.xml
+      # declaring the Cobertura report depends on the GitLab version :(
+      # GitLab < 14.10
+      # cobertura: $PYTHON_PROJECT_DIR/reports/coverage.xml
+      # GitLab >= 14.10
+      # coverage_report:
+      #   coverage_format: cobertura
+      #   path: ​$PYTHON_PROJECT_DIR/reports/coverage.xml
     paths:
       - $PYTHON_PROJECT_DIR/reports/
   rules:
-- 
GitLab