simplesamlphp · tvdijen · Jul 14, 2022 · Jul 4, 2022 · Jul 7, 2022 · Jul 7, 2022
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,53 @@
+name: Documentation
+
+on:
+  push:
+    branches: [ master, release-* ]
+    paths:
+      - '**.md'
+  pull_request:
+    branches: [ master, release-* ]
+    paths:
+      - '**.md'
+
+jobs:
+  quality:
+    name: Quality checks
+    runs-on: [ubuntu-latest]
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Lint markdown files
+        uses: nosborn/github-action-markdown-cli@v3.1.0
+        with:
+          files: .
+          ignore_path: .markdownlintignore
+
+      - name: Perform spell check
+        uses: codespell-project/actions-codespell@master
+        with:
+          path: '**/*.md'
+          check_filenames: true
+          ignore_words_list: tekst
+
+  build:
+    name: Build documentation
+    needs: quality
+    runs-on: [ubuntu-latest]
+
+    steps:
+      - name: Run docs build if any of markdown-files have changed
+        if: steps.changed-files-specific.outputs.any_changed == 'true' && github.event_name != 'pull_request'
+        uses: actions/github-script@v6
+        with:
+          # Token has to be generated on a user account that controls the docs-repository.
+          # The _only_ scope to select is "Access public repositories", nothing more.
+          github-token: ${{ secrets.PAT_TOKEN }}
+          script: |
+            await github.rest.actions.createWorkflowDispatch({
+              owner: 'simplesamlphp',
+              repo: 'docs',
+              workflow_id: 'mk_docs.yml',
+              ref: 'main'
+            })
diff --git a/.github/workflows/php.yml b/.github/workflows/php.yml
@@ -37,7 +37,7 @@ jobs:
           git config --global core.autocrlf false
           git config --global core.eol lf
 
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Get composer cache directory
         id: composer-cache
@@ -91,7 +91,7 @@ jobs:
       - name: Setup problem matchers for PHP
         run: echo "::add-matcher::${{ runner.tool_cache }}/php.json"
 
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Get composer cache directory
         id: composer-cache
@@ -132,7 +132,7 @@ jobs:
       - name: Setup problem matchers for PHP
         run: echo "::add-matcher::${{ runner.tool_cache }}/php.json"
 
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Get composer cache directory
         id: composer-cache
@@ -170,7 +170,7 @@ jobs:
       - name: Setup problem matchers for PHP
         run: echo "::add-matcher::${{ runner.tool_cache }}/php.json"
 
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Get composer cache directory
         id: composer-cache

diff --git a/.markdownlintignore b/.markdownlintignore
@@ -0,0 +1 @@
+vendor/*
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,11 +1,13 @@
 # Contribution guidelines
+
 **SimpleSAMLphp welcomes all contributions**. It is impossible to make a product like this without the efforts of many people, so please don't be shy and share your help with us. Even the tiniest contribution can make a difference!
 
 These guidelines briefly explain how to contribute to SimpleSAMLphp effectively and consistently, making sure to keep high quality standards and making it easier for you to contribute.
 
 [TOC]
 
 ## Team members
+
 Currently, the core team members are:
 
 * Jaime Pérez Crespo, *maintainer and main developer*, UNINETT <jaime.perez@uninett.no>
@@ -22,6 +24,7 @@ We have been lucky enough to have so many people help us through the years. Simp
 ***Big thanks to you all!***
 
 ## First things first
+
 Before embarking yourself in a contribution, please make sure you are familiar with the way SimpleSAMLphp is written, the way it works, and what is required or not.
 
 * Make sure to read [the documentation](https://simplesamlphp.org/docs/stable/). If you use the search engine in the website, please verify that you are reading the latest stable version. If you want to make a change, check [the development branch of the documentation](https://simplesamlphp.org/docs/development/).
@@ -30,39 +33,45 @@ Before embarking yourself in a contribution, please make sure you are familiar w
 * If you think you have discovered a bug, please check the [issue tracker](https://github.com/simplesamlphp/simplesamlphp/issues) and the [pull requests](https://github.com/simplesamlphp/simplesamlphp/pulls) to verify it hasn't been reported already.
 
 ## Contributing code
+
 New features are always welcome, provided they will be useful to someone apart from yourself. Please take a look at the [list of issues](https://github.com/simplesamlphp/simplesamlphp/issues) to see what people are asking for. Our [roadmap](https://simplesamlphp.org/releaseplan) might also be a good place to start if you do not know exactly how you can contribute.
 
 When submitting a pull request, please make sure to account for:
 
 ### Coding standards
+
 * Respect the coding standards. We try to comply with PHP's [PSR-12](http://www.php-fig.org/psr/psr-12/). Pay special attention to the rules below:
-    * Lines should not be longer than 80 characters.
-    * Use **4 spaces** instead of tabs.
-    * Keep the keywords in **lowercase**, including `true`, `false` and `null`.
-    * Make sure your classes work with *autoloading*.
-    * Never include a trailing `?>` in your files.
-    * The first line of every file must be `<?php`.
-    * Use namespaces if you are adding new files.
+  * Lines should not be longer than 80 characters.
+  * Use **4 spaces** instead of tabs.
+  * Keep the keywords in **lowercase**, including `true`, `false` and `null`.
+  * Make sure your classes work with *autoloading*.
+  * Never include a trailing `?>` in your files.
+  * The first line of every file must be `<?php`.
+  * Use namespaces if you are adding new files.
 * Do not include too many changes in every commit. Commits should be focused and address one single problem or feature. By having **multiple, small commits** instead of fewer large ones, it is easier to track what you are doing, revert changes in case of an error and help you make changes if needed.
 * Try to write clean **commit messages**, largely based on the [seven rules](http://chris.beams.io/posts/git-commit/):
-    * Write a **short** subject line, followed by a blank line and a longer explanation.
-    * Prefix the subject line with the component(s) changed, e.g. "docs: Update foo", or "SAML: Don't log bar twice", or "tests: Add tests for quux".
-    * Explain **what and why** in the commit message, not just _how_. Things that seem obvious now might become quite confusing when rediscovered years later.
+  * Write a **short** subject line, followed by a blank line and a longer explanation.
+  * Prefix the subject line with the component(s) changed, e.g. "docs: Update foo", or "SAML: Don't log bar twice", or "tests: Add tests for quux".
+  * Explain **what and why** in the commit message, not just **how**. Things that seem obvious now might become quite confusing when rediscovered years later.
 
 ### Comments, comparisons, and simplicity
+
 * Add comments that describe why/how your code works.
 * Include complete **phpdoc** documentation for every property and method you add. If you change a method or property, make sure to update the existing *phpdoc* accordingly. Do not forget to document all parameters, returned values and exceptions thrown.
 * Use strict comparison operators like `===` and check for specific values when writing tests.
 * Avoid big functions, long nested loops or `if` statements.
 * Try to keep **backwards-compatibility**. Code that breaks current configurations and installations is difficult to deploy, and therefore we try to avoid that as much as possible.
 
 ### Unit tests
+
 Add **unit tests** to verify that your code not only works but also keeps working over time. When adding tests, keep the same directory structure used for regular classes. Try to cover **all your code** with tests. The bigger the test coverage, the more reliable and better our library is. Read our [guidelines](TESTING.md) to learn more about tests.
 
 ### Documentation
+
 In order to keep this library user-friendly, we ask that you add proper **documentation** explaining how to use your new feature or how your code changes things.
 
 ### Pull requests
+
 Please follow all instructions below:
 
 1. Submit your code as a **pull request** in github from a branch with a descriptive name in your own fork of the repository.
@@ -72,6 +81,7 @@ Please follow all instructions below:
 Sometimes it can take a long time before we are able to process your pull requests. Do not get discouraged, we will eventually reach your change. Remember that by following these guidelines, you are making it easier for us to analyze your request so the process will be smooth and fast. We really appreciate you helping us out, not only with your code, but also by following these guidelines.
 
 ## Reporting bugs
+
 Before reporting a bug, please make sure it is indeed a bug. Check [the documentation](https://simplesamlphp.org/docs/stable/) to verify what the intended behaviour is. Review the [issue tracker](https://github.com/simplesamlphp/simplesamlphp/issues) and the [pull requests](https://github.com/simplesamlphp/simplesamlphp/pulls) to see if someone has already reported the same issue.
 
 If you are able, a pull request is much more appreciated than just a new issue. If not, please do not hesitate to open one. It is better to have just an issue report than nothing!
@@ -86,6 +96,7 @@ You can help us diagnose and fix bugs by asking and providing answers to the fol
 * Is this a security issue? If so, how severe is it? How can an attacker exploit it? Read more about security issues in the next section.
 
 ## Reporting vulnerabilities
+
 In case you find a vulnerability in SimpleSAMLphp, or you want to confirm a possible security issue in the software, please get in touch with us through [UNINETT's CERT team](https://www.uninett.no/cert). Please use our PGP public key to encrypt any possibly sensitive data that you may need to submit. We will get back to you as soon as possible according to our working hours in Central European Time.
 
 When reporting a security issue, please add as much information as possible to help us identify, confirm, replicate and fix the problem. In particular, remember to include the following information in your report:
@@ -107,16 +118,19 @@ Finally, be reasonable. We'll do our best to resolve the issue according to our
 You can find the list of security advisories we have published [here](https://simplesamlphp.org/security).
 
 ## Translations
+
 SimpleSAMLphp is translated to many languages, though it needs constant updates from translators, as well as new translations to other languages. For the moment, translations can be contributed as **pull requests**. We are looking at better ways to translate the software that would make your life easier, so stay tuned! You can also join the [translators mailing list](http://groups.google.com/group/simplesamlphp-translation) to keep up to date on the latest news.
 
 Before starting a new translation, decide what style you want to use, whether you want to address the user in a polite manner or not, etc. Be coherent and keep that style through all your translations. If there is already a translation and you want to complete it, make sure to keep the same style used by your fellow translators.
 
-## Documentation
+## Documentation improvements
+
 Did you find a typo in the documentation? Does something make no sense? Did we use poor english? Tell us!
 
 Documentation is included in our own repository in *markdown* format. You can submit pull requests with fixes. If you encounter some feature that is not documented, or the documentation does not reflect the real behaviour of the library, please do not hesitate to open an issue.
 
 Good documentation is key to make things easier for our users!
 
 ## Community
+
 You do not feel capable of contributing with your code, but are using SimpleSAMLphp and can share your knowledge and experience? Please, do so! Join our [users mailing list](http://groups.google.com/group/simplesamlphp) and help other users when you can. Your experience might be valuable for many!
diff --git a/README.md b/README.md
@@ -1,12 +1,11 @@
-SimpleSAMLphp
-=============
+# SimpleSAMLphp
+
 ![Build Status](https://github.com/simplesamlphp/simplesamlphp/workflows/CI/badge.svg?branch=master)
 [![Coverage Status](https://codecov.io/gh/simplesamlphp/simplesamlphp/branch/master/graph/badge.svg)](https://codecov.io/gh/simplesamlphp/simplesamlphp)
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/simplesamlphp/simplesamlphp/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/simplesamlphp/simplesamlphp/?branch=master)
 [![Type coverage](https://shepherd.dev/github/simplesamlphp/simplesamlphp/coverage.svg)](https://shepherd.dev/github/simplesamlphp/simplesamlphp)
 [![BrowserStack Status](https://automate.browserstack.com/badge.svg?badge_key=LzlCL29sZEVDRXJpdGtxZUdITFA3YjYyUFBBYkVVZDVDcG1YZXRaN2pvTT0tLVhCNzkwVUNGVFVjVFVicUg0R1BNR0E9PQ==--f9efb6f330bd98dd6e3c7b816ac2f0982275a872)](https://automate.browserstack.com/public-build/LzlCL29sZEVDRXJpdGtxZUdITFA3YjYyUFBBYkVVZDVDcG1YZXRaN2pvTT0tLVhCNzkwVUNGVFVjVFVicUg0R1BNR0E9PQ==--f9efb6f330bd98dd6e3c7b816ac2f0982275a872)
 
-
 This is the official repository of the SimpleSAMLphp software.
 
 * [SimpleSAMLphp homepage](https://simplesamlphp.org)

diff --git a/docs/index.md b/docs/index.md
@@ -1,34 +1,33 @@
-SimpleSAMLphp Documentation
-===========================
+# SimpleSAMLphp Documentation
 
- * Installation and upgrading
+* Installation and upgrading
   * [Installing SimpleSAMLphp](simplesamlphp-install)
   * [Upgrade notes](simplesamlphp-upgrade-notes)
   * [Installation from the repository](simplesamlphp-install-repo)
   * [Changelog](simplesamlphp-changelog)
- * Using SimpleSAMLphp as a SAML Service Provider
+* Using SimpleSAMLphp as a SAML Service Provider
   * [Service Provider Quickstart](simplesamlphp-sp)
   * [Hosted SP Configuration Reference](./saml:sp)
   * [IdP remote reference](simplesamlphp-reference-idp-remote)
   * [Configuring HTTP-Artifact](./simplesamlphp-artifact-sp)
   * [Using scoping](./simplesamlphp-scoping)
   * [Holder-of-Key profile](simplesamlphp-hok-sp)
- * Using SimpleSAMLphp as a SAML Identity Provider
+* Using SimpleSAMLphp as a SAML Identity Provider
   * [Identity Provider QuickStart](simplesamlphp-idp)
   * [IdP hosted reference](simplesamlphp-reference-idp-hosted)
   * [SP remote reference](simplesamlphp-reference-sp-remote)
   * [Use case: Setting up an IdP for Google Workspace (G Suite / Google Apps)](simplesamlphp-googleapps)
   * [Configuring HTTP-Artifact](./simplesamlphp-artifact-idp)
   * [Identity Provider Advanced Topics](simplesamlphp-idp-more)
   * [Holder-of-Key profile](simplesamlphp-hok-idp)
- * Further topics
+* Further topics
   * [Maintenance and configuration](simplesamlphp-maintenance) - covers session handling, php configuration etc.
   * [Automated Metadata Management](/docs/contrib_modules/metarefresh/simplesamlphp-automated_metadata)
   * [Key rollover](./saml:keyrollover)
   * [Authentication Processing Filters](simplesamlphp-authproc) - attribute filtering, attribute mapping, consent, group generation etc.
   * [State Information Lost](simplesamlphp-nostate) - more about this common error message
   * [Advanced features](simplesamlphp-advancedfeatures) - covers bridging protocols, attribute filtering, etc.
- * SimpleSAMLphp Modules
+* SimpleSAMLphp Modules
   * [Documentation for specific modules](/docs/contributed_modules.html)
   * [Theming SimpleSAMLphp](simplesamlphp-theming)
   * [Creating authentication sources](./simplesamlphp-authsource)