From 8df35e1b1b9fb7a7bc2922fa6b03f4431f3eafc0 Mon Sep 17 00:00:00 2001 From: Ariel Schulz Date: Tue, 15 Jul 2025 13:29:33 +0200 Subject: [PATCH 1/7] Update user guide for branch protections --- doc/changes/unreleased.md | 6 +++++- doc/user_guide/workflows.rst | 3 +++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/changes/unreleased.md b/doc/changes/unreleased.md index 0f3925472..b31575873 100644 --- a/doc/changes/unreleased.md +++ b/doc/changes/unreleased.md @@ -2,4 +2,8 @@ ## Bugfixes -* #489: Fixed .pre-commit-config.yaml to use existing nox tasks \ No newline at end of file +* #489: Fixed .pre-commit-config.yaml to use existing nox tasks + +## Documentation + +* #488: Updated user guide to make clearer under which conditions branch protections based on GitHub actions can be enacted diff --git a/doc/user_guide/workflows.rst b/doc/user_guide/workflows.rst index e53c78902..ea4752e48 100644 --- a/doc/user_guide/workflows.rst +++ b/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. From 5fa089b6f34c772bf2a6daa085ca22a72d7f9904 Mon Sep 17 00:00:00 2001 From: Ariel Schulz Date: Tue, 15 Jul 2025 14:02:54 +0200 Subject: [PATCH 2/7] Update pull_request_template --- .../pull_request_template.md | 7 ----- .github/pull_request_template.md | 27 +++++++++++++++++++ doc/changes/unreleased.md | 4 +++ .../pull_request_template.md | 16 ----------- .../templates/github/pull_request_template.md | 27 +++++++++++++++++++ 5 files changed, 58 insertions(+), 23 deletions(-) delete mode 100644 .github/PULL_REQUEST_TEMPLATE/pull_request_template.md create mode 100644 .github/pull_request_template.md delete mode 100644 exasol/toolbox/templates/github/PULL_REQUEST_TEMPLATE/pull_request_template.md create mode 100644 exasol/toolbox/templates/github/pull_request_template.md diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md deleted file mode 100644 index 075341789..000000000 --- a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ /dev/null @@ -1,7 +0,0 @@ -# Checklist - -* [ ] Have you updated the changelog? -* [ ] Have you updated the cookiecutter-template? -* [ ] Are you mentioning the issue which this PullRequest fixes ("Fixes...") - -Note: If any of the above is not relevant to your PR just check the box. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..77e2a6f23 --- /dev/null +++ b/.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? +* [ ] 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? diff --git a/doc/changes/unreleased.md b/doc/changes/unreleased.md index b31575873..1d96ac1d2 100644 --- a/doc/changes/unreleased.md +++ b/doc/changes/unreleased.md @@ -7,3 +7,7 @@ ## Documentation * #488: Updated user guide to make clearer under which conditions branch protections based on GitHub actions can be enacted + +## Refactoring + +* #382: Updated pull_request_template.md to reflect checks we should regularly perform diff --git a/exasol/toolbox/templates/github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/exasol/toolbox/templates/github/PULL_REQUEST_TEMPLATE/pull_request_template.md deleted file mode 100644 index e8cafdd30..000000000 --- a/exasol/toolbox/templates/github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ /dev/null @@ -1,16 +0,0 @@ -**< PR SPECIFIC CONTENT >** - -------- -# ✔ Checklist(s) - -* [ ] Is the title of the Pull Request correct? -* [ ] Is the title of the corresponding issue correct? -* [ ] Have you updated the changelog? -* [ ] Have you checked to ensure there aren't other open Pull Requests for the same update/change? -* [ ] Are you mentioning the issue which this PullRequest fixes ("Fixes...") - -## 🔐 Security -## 🐞 Bug -## ✨ Feature -## 🔧 Refactoring -## 📚 Documentation diff --git a/exasol/toolbox/templates/github/pull_request_template.md b/exasol/toolbox/templates/github/pull_request_template.md new file mode 100644 index 000000000..14fbf3cf1 --- /dev/null +++ b/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? +* [ ] 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`? From f8d09f2d2ab507d7b6aaf5aefd08e3b614203b5e Mon Sep 17 00:00:00 2001 From: Ariel Schulz Date: Tue, 15 Jul 2025 14:07:24 +0200 Subject: [PATCH 3/7] Fix typos --- doc/user_guide/migrating.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/user_guide/migrating.rst b/doc/user_guide/migrating.rst index bca7be057..02ca28bcf 100644 --- a/doc/user_guide/migrating.rst +++ b/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 `_ - ✓ - ✓ - ✓ - ✓ - ✓ - - ✓/✗ partialy - - ✓/✗ partialy + - ✓/✗ partially + - ✓/✗ partially * - `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 `_ - ✓ @@ -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 From 6f2fe7d47838958c26d1bcf1892f4f1642ae4320 Mon Sep 17 00:00:00 2001 From: Ariel Schulz Date: Tue, 15 Jul 2025 14:10:50 +0200 Subject: [PATCH 4/7] Add information to user guide about nox tasks for links & how to configure --- doc/user_guide/customization.rst | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/doc/user_guide/customization.rst b/doc/user_guide/customization.rst index 4d7bda065..2327327ec 100644 --- a/doc/user_guide/customization.rst +++ b/doc/user_guide/customization.rst @@ -3,10 +3,23 @@ Customization .. _plugins: +Nox Tasks `links:x` +--------------------- + +We have two nox tasks to check links present in our 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. @@ -14,11 +27,11 @@ This action may have a widespread impact by forcibly stopping execution, potenti .. attention:: Doing a hard exit using ``session.error`` should be an measure of last resort. -.. note:: +.. note:: - Even though the plugin mechanism utilizes `pluggy `_ 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 `_ + Even though the plugin mechanism utilizes `pluggy `_ 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 `_ can definitely enhance understanding of the hook mechanism. From 7f2b3d8a6b8d4bd22ae779398453bb7be4d22ef4 Mon Sep 17 00:00:00 2001 From: Ariel Schulz Date: Tue, 15 Jul 2025 14:12:09 +0200 Subject: [PATCH 5/7] Fix wrong number in changelog --- doc/changes/unreleased.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/changes/unreleased.md b/doc/changes/unreleased.md index 1d96ac1d2..9c191d20e 100644 --- a/doc/changes/unreleased.md +++ b/doc/changes/unreleased.md @@ -10,4 +10,4 @@ ## Refactoring -* #382: Updated pull_request_template.md to reflect checks we should regularly perform +* #482: Updated pull_request_template.md to reflect checks we should regularly perform From 18ef0e767aab0a43932ec98c329af6878a452f8a Mon Sep 17 00:00:00 2001 From: Ariel Schulz Date: Tue, 15 Jul 2025 14:28:37 +0200 Subject: [PATCH 6/7] Exclude version from source code consideration. This is benefitial particularly for new/smaller projects --- project-template/{{cookiecutter.repo_name}}/pyproject.toml | 1 + pyproject.toml | 1 + 2 files changed, 2 insertions(+) diff --git a/project-template/{{cookiecutter.repo_name}}/pyproject.toml b/project-template/{{cookiecutter.repo_name}}/pyproject.toml index 04ddf0194..1cca979c9 100644 --- a/project-template/{{cookiecutter.repo_name}}/pyproject.toml +++ b/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" diff --git a/pyproject.toml b/pyproject.toml index f53cad30a..7ec8638a4 100644 --- a/pyproject.toml +++ b/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" From 0c51781464eb568147e1cd5bf4e2d6a5033afc3a Mon Sep 17 00:00:00 2001 From: Ariel Schulz Date: Wed, 16 Jul 2025 08:45:48 +0200 Subject: [PATCH 7/7] Update to be clearer who offers what --- doc/user_guide/customization.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/customization.rst b/doc/user_guide/customization.rst index 2327327ec..dff0af383 100644 --- a/doc/user_guide/customization.rst +++ b/doc/user_guide/customization.rst @@ -6,7 +6,7 @@ Customization Nox Tasks `links:x` --------------------- -We have two nox tasks to check links present in our documentation: +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