Documentation/488 enhance user guide

.github/pull_request_template.md

@@ -0,0 +1,27 @@
+# Checklist
+
+Note: If any of the items in the checklist are not relevant to your PR, just check the box.
+
+## For any Pull Request
+
+Is the following correct:
+* [ ] the title of the Pull Request?
+* [ ] the title of the corresponding issue?
+* [ ] there are no other open [Pull Requests](../../../../pulls) for the same update/change? <!-- markdown-link-check-disable-line -->
+* [ ] that the issue which this Pull Request fixes ("Fixes...") is mentioned?
+
+## When Changes Were Made
+
+Did you:
+* [ ] update the changelog?
+* [ ] update the cookiecutter-template?
+* [ ] update the implementation?
+* [ ] check coverage and add tests: unit tests and, if relevant, integration tests?
+* [ ] update the User Guide & other documentation?
+* [ ] resolve any failing CI criteria (incl. Sonar quality gate)?
+
+## When Preparing a Release
+
+Have you:
+* [ ] thought about version number (major, minor, patch)?
+* [ ] checked Exasol packages for updates and resolved open vulnerabilities, if easily possible?

doc/changes/unreleased.md

@@ -5,3 +5,11 @@
 * #489: Fixed .pre-commit-config.yaml to use existing nox tasks
 * #490: Fixed artifacts:validate & sonar:check to work for newly created projects
 * #484: Fixed hint command text in version.py to include -s for executing nox task
+
+## Documentation
+
+* #488: Updated user guide to make clearer under which conditions branch protections based on GitHub actions can be enacted
+
+## Refactoring
+
+* #482: Updated pull_request_template.md to reflect checks we should regularly perform

doc/user_guide/customization.rst

@@ -3,22 +3,35 @@ Customization
 
 .. _plugins:
 
+Nox Tasks `links:x`
+---------------------
+
+PTB offers two nox sessions to check hyperlinks in your documentation:
+ * `links:list` - List all the links within the documentation
+ * `links:check` - Checks whether all links in the documentation are accessible
+
+`links:check` is run in the CI `checks.yml`. If this step fails in the CI, it will cause
+the build to break. Please check the output & manually resolve the issues. There might
+be some cases where you need to update your `doc/conf.py` with specific values for the allowed
+options for the [Linkcheck Builder](https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder).
+
+
 Nox Task Plugins
 ----------------
 
-Some Nox task allow for implementing custom hooks to be executed within the Nox workflow.
+Some Nox tasks allow for implementing custom hooks to be executed within the Nox workflow.
 To ensure a predictable environment, plugins should be written to handle exceptions gracefully.
 If a plugin encounters a critical situation where it cannot continue execution, it should call the ``error``
 method on the session object, effectively halting the execution process.
 This action may have a widespread impact by forcibly stopping execution, potentially affecting other plugins and code paths.
 
 .. attention:: Doing a hard exit using ``session.error`` should be an measure of last resort.
 
-.. note:: 
+.. note::
 
-    Even though the plugin mechanism utilizes `pluggy <https://pluggy.readthedocs.io/en/stable/>`_ under the hood, it does 
-    not currently support all scenarios and features with which one may be familiar from pytest, or other tools and 
-    frameworks based on pluggy. Nevertheless, a look at pluggy's `documentation <https://pluggy.readthedocs.io/en/stable/>`_ 
+    Even though the plugin mechanism utilizes `pluggy <https://pluggy.readthedocs.io/en/stable/>`_ under the hood, it does
+    not currently support all scenarios and features with which one may be familiar from pytest, or other tools and
+    frameworks based on pluggy. Nevertheless, a look at pluggy's `documentation <https://pluggy.readthedocs.io/en/stable/>`_
     can definitely enhance understanding of the hook mechanism.
 
 

doc/user_guide/migrating.rst

@@ -152,14 +152,14 @@ _______
 
 4. Introduce GitHub Workflows
 -----------------------------
-Install the GitHub workflows provided by the :code:`python-toolbox` for futher details refer to the section :ref:`GitHub Workflows`.
+Install the GitHub workflows provided by the :code:`python-toolbox` for further details refer to the section :ref:`GitHub Workflows`.
 
 .. attention::
    This is just guidance. If you have a good understanding of the standard project setup, technologies, and tools used, feel free to diverge at any point or exercise your own judgment.
 
 
-Migration Progess
-+++++++++++++++++
+Migration Progress
+++++++++++++++++++
 
 Could be tracked in a format and based on the information listed in the real life example bellow.
 
@@ -218,15 +218,15 @@ Could be tracked in a format and based on the information listed in the real lif
       - ✓
       - ✓
       - ✓
-      - ✓/✗ partialy
+      - ✓/✗ partially
     * - `ITDE <https://github.com/exasol/integration-test-docker-environment>`_
       - ✓
       - ✓
       - ✓
       - ✓
       - ✓
-      - ✓/✗ partialy
-      - ✓/✗ partialy
+      - ✓/✗ partially
+      - ✓/✗ partially
     * - `schemas <https://github.com/exasol/schemas>`_
       - ✓
       - ✓
@@ -239,9 +239,9 @@ Could be tracked in a format and based on the information listed in the real lif
       - ✓
       - ✓
       - ✓
-      - ✓/✗ partialy
+      - ✓/✗ partially
       - ✓
-      - ✓/✗ partialy
+      - ✓/✗ partially
       - ✗
     * - `harlequin-exasol <https://github.com/Nicoretti/harlequin-exasol>`_
       - ✓
@@ -268,7 +268,7 @@ Could be tracked in a format and based on the information listed in the real lif
     * - PYPI
       - Project can be build and published to `PyPi`_
     * - Sphinx Docs
-      - The project doumentation is `Sphinx`_ based
+      - The project documentation is `Sphinx`_ based
     * - nox
       - The projects automated tasks are executed using the `Nox`_ task runner
     * - toolbox-tasks

doc/user_guide/workflows.rst

@@ -44,3 +44,6 @@ The exasol-toolbox ships with various GitHub workflow templates. To leverage the
 ++++++++++++++++++++++++++++
 
 The best and most maintainable way to have solid branch protection (:code:`Settings/Branches/main`) is to require the workflow :code:`CI / Allow Merge` to pass successfully.
+
+.. note::
+   Setting the required status checks to pass before merging is only possible after running a CI build at **least once** on the affected branch.

exasol/toolbox/templates/github/pull_request_template.md

@@ -0,0 +1,27 @@
+# Checklist
+
+Note: If any of the items in the checklist are not relevant to your PR, just check the box.
+
+## For any Pull Request
+
+Is the following correct:
+* [ ] the title of the Pull Request?
+* [ ] the title of the corresponding issue?
+* [ ] there are no other open [Pull Requests](../../../../pulls) for the same update/change? <!-- markdown-link-check-disable-line -->
+* [ ] that the issue which this Pull Request fixes ("Fixes...") is mentioned?
+
+## When Changes Were Made
+
+Did you:
+* [ ] update the changelog?
+* [ ] update the implementation?
+* [ ] check coverage and add tests: unit tests and, if relevant, integration tests?
+* [ ] update the User Guide & other documentation?
+* [ ] resolve any failing CI criteria (incl. Sonar quality gate)?
+
+## When Preparing a Release
+
+Have you:
+* [ ] thought about version number (major, minor, patch)?
+* [ ] checked Exasol packages for updates and resolved open vulnerabilities, if easily possible?
+  * [ ] executed `poetry run -- tbx workflow update`?

project-template/{{cookiecutter.repo_name}}/pyproject.toml

@@ -67,3 +67,4 @@ ignore_errors = true
 projectKey = "com.exasol:{{cookiecutter.repo_name}}"
 hostUrl = "https://sonarcloud.io"
 organization = "exasol"
+exclusions = "exasol/{{cookiecutter.package_name}}/version.py"

pyproject.toml

@@ -120,3 +120,4 @@ sphinx-multiversion = 'exasol.toolbox.sphinx.multiversion:main'
 projectKey = "com.exasol:python-toolbox"
 hostUrl = "https://sonarcloud.io"
 organization = "exasol"
+exclusions = "exasol/toolbox/version.py"