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 52bc9a3f1..d3d64eaac 100644 --- a/doc/changes/unreleased.md +++ b/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 diff --git a/doc/user_guide/customization.rst b/doc/user_guide/customization.rst index 4d7bda065..dff0af383 100644 --- a/doc/user_guide/customization.rst +++ b/doc/user_guide/customization.rst @@ -3,10 +3,23 @@ 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. @@ -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. 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 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. 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`? 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"