From 57dab8438fcbec7abd7625e9327da0b621626540 Mon Sep 17 00:00:00 2001
From: Cristian Le <git@lecris.dev>
Date: Tue, 26 Dec 2023 17:47:34 +0100
Subject: [PATCH] doc: Making check results look green

Signed-off-by: Cristian Le <git@lecris.dev>
---
 README.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/README.md b/README.md
index 9636107..11960f7 100644
--- a/README.md
+++ b/README.md
@@ -123,6 +123,8 @@ Whether this check decided that the job matrix succeeded.
 
 ## Gotchas
 
+### Experimental matrix jobs
+
 An attentive reader may have noticed that there is no clear way to
 allow failures for specific job generated by matrixes in a simple
 manner, through action inputs. This is due to the fact that those
@@ -174,6 +176,40 @@ jobs:
 ...
 ```
 
+### Displaying the overall workflow result
+
+The GitHub commit and pull-request checks will still display as if the workflows
+have failed (the red cross on the checks). To clarify the actual status of the
+workflow taking into account [experimental matrix jobs] and `allowed-failures`
+you can do two things:
+
+#### Display the workflow badge
+
+See the [github documentation][workflow-badge-doc] about how to include the
+workflow status on the top-level README page. Simply point this to the workflow
+that runs the alls-green action, e.g.:
+```markdown
+![CI-status](https://github.com/user/repo/actions/workflows/ci.yml/badge.svg?branch=main&event=push)
+```
+
+#### Masking the check results
+
+If you know the exact step that may fail, you can use
+[`steps[*].continue-on-error`][continue-on-error] to mask the job's result, e.g.:
+```yaml
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    matrix:
+      python-version: [ "3.11", "3.x" ]
+      includes:
+        - python-version: "3.x"
+          experimental: true
+    steps:
+      - uses: actions/checkout@v5
+      - runs: do-test
+        continue-on-error: ${{ github.event_name == 'push' && matrix.experimental}}
+```
 
 ## Does anybody actually use this?
 
@@ -218,6 +254,8 @@ The contents of this project is released under the
 [BSD 3-clause license]: LICENSE.md
 [conda]: https://github.com/conda/conda
 [coveragepy]: https://github.com/nedbat/coveragepy
+[continue-on-error]: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepscontinue-on-error
+[experimental matrix jobs]: #experimental-matrix-jobs
 [forum:check]:
 https://github.com/orgs/community/discussions/26733#discussioncomment-3253151
 [gating]: https://gating.dev
@@ -228,6 +266,7 @@ https://github.com/orgs/community/discussions/26733#discussioncomment-3253151
 [spaceship-prompt]: https://github.com/spaceship-prompt/spaceship-prompt
 [structlog]: https://github.com/hynek/structlog
 [Towncrier]: https://github.com/twisted/towncrier
+[workflow-badge-doc]: https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge
 [Zuul]: https://zuul-ci.org
 [@aio-libs]: https://github.com/aio-libs
 [@CherryPy]: https://github.com/cherrypy