Merge branch 'main' into feature/#73-Add-nox-target-for-auditing-workspaces-in-reagard-to-known-vunerabilities

Author: Jannis-Mittenzwei

doc/changes/changelog.md

@@ -1,6 +1,7 @@
 # Changelog
 
 * [unreleased](unreleased.md)
+* [0.21.0](changes_0.21.0.md)
 * [0.20.0](changes_0.20.0.md)
 * [0.19.0](changes_0.19.0.md)
 * [0.18.0](changes_0.18.0.md)
@@ -29,6 +30,7 @@
 hidden:
 ---
 unreleased
+changes_0.21.0
 changes_0.20.0
 changes_0.19.0
 changes_0.18.0

doc/changes/changes_0.21.0.md

@@ -0,0 +1,29 @@
+# 0.21.0 - 2025-02-25
+
+## ✨ Features
+
+* Added tbx task for markdown formating of .lint.json
+* Added a Nox task for dependencies packages and their licenses with Markdown output
+* [#293](https://github.com/exasol/python-toolbox/issues/293): Added `py.typed` file
+
+## 🐞 Fixed
+* Fixed an issue in the CI workflow that caused it to be executed twice on the initial push of a PR if the PR branch was on the repo itself.
+
+    🚨 Attention: Due to these changes, the workflows will no longer be executed if the PR comes from a branch not located in this repository.
+                  As third-party contributions from outside forks are rare to nearly non-existent, this downside was considered a reasonable trade-off at this time.
+
+## 📚 Documentation
+* Updated design doc (Added known Issues)
+* Updated migration progress table
+* Updated the FAQ with an entry about the ``isort`` compatibility issue
+* [#351](https://github.com/exasol/python-toolbox/issues/351), [#352](https://github.com/exasol/python-toolbox/issues/352): updated user guide
+
+## 🔧 Changed
+* Updated `actions/upload-artifacts` version to `4.6.0`
+
+## 🔩 Internal
+* Relocked dependencies
+* Update referenced github actions
+
+## ⚒️ Refactorings
+* [#339](https://github.com/exasol/python-toolbox/issues/339): Secret ALTERNATIVE_GITHUB_TOKEN removed from GitHub workflows

doc/changes/unreleased.md

@@ -2,27 +2,4 @@
 
 ## ✨ Added
 
-* added tbx task for markdown formating of .lint.json
-* Added a Nox task for dependencies packages and their licenses with Markdown output
 * [#73](https://github.com/exasol/python-toolbox/issues/73): Add nox target for auditing work spaces in regard to known vulnerabilities
-
-## 🐞 Fixed
-* Fixed an issue in the CI workflow that caused it to be executed twice on the initial push of a PR if the PR branch was on the repo itself.
-
-    🚨 Attention: Due to these changes, the workflows will no longer be executed if the PR comes from a branch not located in this repository.
-                  As third-party contributions from outside forks are rare to nearly non-existent, this downside was considered a reasonable trade-off at this time.
-
-## 📚 Documentation
-* Updated design doc (Added known Issues)
-* Updated migration progress table
-* Updated the FAQ with an entry about the ``isort`` compatibility issue
-
-## 🔧 Changed
-* Updated `actions/upload-artifacts` version to `4.6.0`
-
-## 🔩 Internal
-* Relocked dependencies
-* Update referenced github actions
-
-## ⚒️ Refactorings
-* [#339](https://github.com/exasol/python-toolbox/issues/339): Secret ALTERNATIVE_GITHUB_TOKEN removed from GitHub workflows

doc/user_guide/features.rst

@@ -0,0 +1,34 @@
+Features
+========
+
+Uniform Project Layout
+----------------------
+
+PTB expects a default project layout following "convention over configuration" when possible and reasonable.
+See the cookie-cutter project template for details, which is part of the python-toolbox workspace and can be found in directory `project-template`.
+You can also generate a project from the template to explore the default structure.
+For more details on this, please check out section `"getting started" <getting_started.html>`_ section.
+
+Nox
+---
+
+The most central tool when interacting with the toolbox is :code:`nox`, which is the task runner used across all of Exasol's Python-based projects.
+The toolbox itself provides various standard tasks and a plugin mechanism to extend these tasks if needed. For more information regarding nox, please visit the `nox homepage <http://nox.thea.codes/en/stable/>`_.
+
+Central files in regards to nox and the toolbox are:
+
+- noxfile.py: Standard nox configuration/setup file
+- noxconfig.py: Exasol-specific file containing additional information needed by the standard tasks of the toolbox
+
+Important Nox Commands
+^^^^^^^^^^^^^^^^^^^^^^
+
+* :code:`nox -l` shows a list of all available nox tasks
+* :code:`nox -s <tasks>` run the specified task(s)
+    * :code:`nox -s test:typing` runs the type checker on the project
+    * :code:`nox -s docs:clean docs:build docs:open`
+        #. first task removes the documentation folder
+        #. second one builds the documentation
+        #. last one opens the documentation in the web browser
+* :code:`nox` without :code:`-s` runs the default task which is
+    * :code:`nox -s project:fix` this command runs automated fixes on the code

doc/user_guide/how_to_release.rst

@@ -0,0 +1,12 @@
+How to Release?
+===============
+
+#.  Use :code:`nox -s release:prepare` to prepare the project for a new release.
+#.  Merge your **Pull Request** to the **default branch**
+#.  Use :code:`git remote show origin | sed -n '/HEAD branch/s/.*: //p'` to output the **default branch**
+#.  Use :code:`git checkout <default branch>` Switch to the **default branch**
+#.  Use :code:`git pull` to update branch
+#.  Use :code:`TAG=<name>` to set a variable named **"TAG"**
+#.  Use :code:`git tag "${TAG}"` to create a new tag in your repo
+#.  Use :code:`git push origin "${TAG}"` to push it to remote
+#.  GitHub workflow **CD** reacts on this tag and starts the release process

doc/user_guide/overview.rst

@@ -6,8 +6,9 @@
 .. toctree::
     :maxdepth: 2
 
-    overview
     getting_started
+    features
     workflows
     customization
     migrating
+    how_to_release

doc/user_guide/user_guide.rst

@@ -17,7 +17,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Setup Python & Poetry Environment
-        uses: exasol/python-toolbox/.github/actions/python-environment@0.20.0
+        uses: exasol/python-toolbox/.github/actions/python-environment@0.21.0
 
       - name: Build Artifacts
         run: poetry build

exasol/toolbox/py.typed

@@ -14,7 +14,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Setup Python & Poetry Environment
-        uses: exasol/python-toolbox/.github/actions/python-environment@0.20.0
+        uses: exasol/python-toolbox/.github/actions/python-environment@0.21.0
 
       - name: Check Tag Version
         # make sure the pushed/created tag matched the project version