Address findings from team retro (#289)

Author: Nicoretti

.pre-commit-config.yaml

@@ -1,15 +1,25 @@
-default_stages: [ commit ]
+default_stages: [ pre-commit, pre-push ]
 repos:
 
   - repo: local
     hooks:
       - id: code-format
         name: code-format
         types: [ python ]
-        files: "pyproject.toml"
         pass_filenames: false
         language: system
-        entry: poetry run nox -s fix
+        entry: poetry run nox -s project:fix
+        stages: [ pre-commit ]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: check-yaml
+        stages: [ pre-commit ]
+      - id: end-of-file-fixer
+        stages: [ pre-commit ]
+      - id: trailing-whitespace
+        stages: [ pre-commit ]
 
   - repo: local
     hooks:
@@ -18,7 +28,8 @@ repos:
         types: [ python ]
         pass_filenames: false
         language: system
-        entry: poetry run nox -s type-check
+        entry: poetry run nox -s lint:typing
+        stages: [ pre-push ]
 
   - repo: local
     hooks:
@@ -27,11 +38,5 @@ repos:
         types: [ python ]
         pass_filenames: false
         language: system
-        entry: poetry run nox -s lint
-
-  - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
-    hooks:
-      - id: check-yaml
-      - id: end-of-file-fixer
-      - id: trailing-whitespace
+        entry: poetry run nox -s lint:code
+        stages: [ pre-push ]

doc/_static/github-workflows.png

@@ -142,8 +142,8 @@ and adjust the following settings to your project needs:
     :language: toml
     :start-after: # Tooling
 
-5. Make the toolbox task available
-++++++++++++++++++++++++++++++++++
+5. Make the toolbox tasks available
++++++++++++++++++++++++++++++++++++
 In order to use the standard toolbox task via nox, just import them in your *noxfile.py*.
 If you only need the standard tasks provided by the toolbox your *noxfile.py* is straight
 forward and you just can use the example *noxfile.py* bellow.
@@ -161,10 +161,12 @@ forward and you just can use the example *noxfile.py* bellow.
 
 
 
-6. Setup the pre-commit hooks
-+++++++++++++++++++++++++++++
+6. Setup the pre-commit hooks [optional]
+++++++++++++++++++++++++++++++++++++++++
+
+#. Add a :code:`.pre-commit-config.yaml` file to your project root
 
-#. Add the following .pre-commit-config.yaml to your project root
+    If you want to reuse Nox tasks in the pre-commit hooks, feel free to get some inspiration from the Python toolbox itself:
 
     .. literalinclude:: ../../.pre-commit-config.yaml
        :language: yaml
@@ -173,7 +175,7 @@ forward and you just can use the example *noxfile.py* bellow.
 
     .. code-block:: shell
 
-        poetry run pre-commit install
+        poetry run pre-commit install --hook-type pre-commit --hook-type pre-push
 
 7. Go 🥜
 +++++++++++++

doc/user_guide/getting_started.rst

@@ -1,26 +1,25 @@
-Github Workflows
+GitHub Workflows
 ================
 
-The exasol-toolbox ships with various GitHub workflows. By default, we suggest installing all of them,
-while the core workflows are:
+.. figure:: ../_static/github-workflows.png
+    :alt: GitHub Workflow Example
 
-**Workflows**:
+The exasol-toolbox ships with various GitHub workflow templates. To leverage the full feature set of the toolbox, you should use them.
 
-* CI
-    Verifies PRs and regularly checks the project.
+.. attention::
 
-* CD
-    Publishes releases of the project.
+   Generally, it is advised to install/use all workflows provided by the toolbox as a whole due to their interdependencies.
 
-* PR-Merge
-    Validates merges and updates the documentation.
+   However, if you know what you are doing and are well-versed in GitHub workflows and actions, you can use just select individual ones or use them as inspiration. Still, an individual approach is likely to be more error-prone.
 
+.. note::
 
-The toolbox command itself, :code:`tbx`, provides various CLI functions to help you maintain those workflows.
-For further help, run the command :code:`tbx workflow --help`.
+    The toolbox command itself, :code:`tbx`, provides various CLI functions to help you maintain those workflows.
+    For further help, run the command :code:`tbx workflow --help`.
 
-1. Configure your project
-+++++++++++++++++++++++++
+
+1. Configure the GitHub project
++++++++++++++++++++++++++++++++
 
 * Make sure your GitHub project has access to a deployment token for PyPi with the following name: **PYPI_TOKEN**. It should be available to the repository either as an Organization-, Repository-, or Environment-secret.
 

doc/user_guide/workflows.rst

@@ -36,7 +36,6 @@ def check(session: Session) -> None:
     context = _context(session, coverage=True)
     py_files = [f"{file}" for file in python_files(PROJECT_CONFIG.root)]
     _version(session, Mode.Check, PROJECT_CONFIG.version_file)
-    _pyupgrade(session, py_files)
     _code_format(session, Mode.Check, py_files)
     _pylint(session, py_files)
     _type_check(session, py_files)

exasol/toolbox/nox/tasks.py

@@ -22,7 +22,7 @@ jobs:
         uses: exasol/python-toolbox/.github/actions/[email protected]
 
       - name: Check Version(s)
-        run: poetry run version-check `poetry run python -c "from noxconfig import PROJECT_CONFIG; print(PROJECT_CONFIG.version_file)"`
+        run: |
           echo "Please enable the version check by replacing this output with shell command bellow:"
           echo ""
           echo "poetry run version-check <<VERSION_PY>>"