From 9264e4f6ed58c39cc7d6846418509c262cf02e6d Mon Sep 17 00:00:00 2001 From: jana-selva Date: Fri, 30 Oct 2026 11:24:35 +0530 Subject: [PATCH 1/2] #988: Split PTB maintenance skill --- .agents/skills/maintain-ptb/SKILL.md | 30 ++++++ .../references/coding-guidelines.md | 43 ++++++++ .../maintain-ptb/references/source-routing.md | 95 ++++++++++++++++++ doc/changes/unreleased.md | 4 + doc/developer_guide/agent_skills.rst | 12 +++ .../features/agent_skills/index.rst | 4 +- .../skills/exasol-python-toolbox/SKILL.md | 55 +++++------ .../references/coding-guidelines.md | 70 +++---------- .../references/common-workflows.md | 47 ++++----- .../references/nox-sessions.md | 4 +- .../references/source-routing.md | 98 ------------------- test/integration/project-template/nox_test.py | 2 +- .../exasol-python-toolbox/eval_cases.yml | 18 ++-- test/unit/skills_test.py | 39 ++++++-- 14 files changed, 286 insertions(+), 235 deletions(-) create mode 100644 .agents/skills/maintain-ptb/SKILL.md create mode 100644 .agents/skills/maintain-ptb/references/coding-guidelines.md create mode 100644 .agents/skills/maintain-ptb/references/source-routing.md delete mode 100644 exasol/toolbox/skills/exasol-python-toolbox/references/source-routing.md diff --git a/.agents/skills/maintain-ptb/SKILL.md b/.agents/skills/maintain-ptb/SKILL.md new file mode 100644 index 000000000..b54dc6df1 --- /dev/null +++ b/.agents/skills/maintain-ptb/SKILL.md @@ -0,0 +1,30 @@ +--- +name: maintain-ptb +description: "Maintain and extend the Exasol Python Toolbox repository itself. Covers PTB source code, Nox sessions, configuration, workflow templates, packaged agent skills, tests, documentation, and the project template." +--- + +# Maintain Exasol Python Toolbox + +Use this skill for changes to the `python-toolbox` repository. Use the packaged +`exasol-python-toolbox` skill in downstream projects that consume PTB. + +## Task routing + +Select the reference that matches the task: + +- To locate implementation, templates, tests, or documentation, read + `references/source-routing.md`. +- To change PTB design, source code, Nox sessions, workflow templates, the + project template, or packaged skills, read `references/coding-guidelines.md`. + +## Maintenance rules + +- Read the implementation and its tests before changing or explaining exact + behavior. +- Preserve the standard PTB task interface used by downstream projects. +- Run `project:check` when a change affects shared behavior, CI, or release + readiness. +- Update tests, user documentation, and `doc/changes/unreleased.md` with public + behavior changes. +- Keep repository-maintenance guidance in this local skill. Limit skills below + `exasol/toolbox/skills/` to downstream usage guidance. diff --git a/.agents/skills/maintain-ptb/references/coding-guidelines.md b/.agents/skills/maintain-ptb/references/coding-guidelines.md new file mode 100644 index 000000000..994387da3 --- /dev/null +++ b/.agents/skills/maintain-ptb/references/coding-guidelines.md @@ -0,0 +1,43 @@ +# Coding Guidelines for PTB Maintenance + +PTB is a development dependency and a task interface for Exasol Python +projects. Preserve the conventions that let projects use the same commands and +automation. + +Use `doc/design.rst` for PTB design principles. Use the matching user-guide +feature page for current public behavior. + +## Design rules + +- Treat PTB as development tooling. Keep PTB imports in development code. +- Prefer conventions. Add configuration when a project needs behavior beyond + the convention. +- Use `pyproject.toml` for static tool configuration. +- Use `noxconfig.py` and `PROJECT_CONFIG` for dynamic project configuration. +- Use plugin hooks or explicit extension points for project-specific work. +- Keep GitHub workflows as orchestration. Put shared task logic in Python + functions or Nox sessions. +- Add PTB features in response to concrete project needs. Move project logic + into PTB when multiple projects need the same behavior. +- Define user-facing Nox sessions in `exasol/toolbox/nox/`. Put reusable logic + below `exasol/toolbox/util/` in functions that receive the Nox `Session` when + needed. + +## Generated projects and workflows + +- Check generated workflows after workflow-template changes. Generate them + when the source template, configuration, or patch intentionally changes + their output. +- Update the project-template tests when a change affects newly created + projects. + +## Agent skills + +- Put downstream runtime skills below `exasol/toolbox/skills/`. The + `skills:install` session installs every skill in that package into consuming + projects. +- Put PTB repository skills below `.agents/skills/` so they remain local to the + repository. +- Limit packaged skills to downstream workflows and public PTB interfaces. +- Cover packaged-skill changes with evaluation cases, packaging tests, + installation tests, and user documentation. diff --git a/.agents/skills/maintain-ptb/references/source-routing.md b/.agents/skills/maintain-ptb/references/source-routing.md new file mode 100644 index 000000000..137216df5 --- /dev/null +++ b/.agents/skills/maintain-ptb/references/source-routing.md @@ -0,0 +1,95 @@ +# PTB Maintainer Source Routing + +Use this reference to find the source file for exact PTB behavior. Read the +implementation and related tests before changing or explaining it. + +## Project entry points + +- `pyproject.toml`: package data, dependencies, and tool configuration. +- `noxfile.py`: local Nox entry point. +- `noxconfig.py`: PTB's `PROJECT_CONFIG` and release hooks. +- `README.rst`: project overview. +- `doc/design.rst`: PTB design rules. + +## Configuration + +- `exasol/toolbox/config.py`: `BaseConfig`, computed configuration fields, + supported versions, paths, workflow variables, and plugin validation. +- `exasol/toolbox/nox/plugin.py`: Nox plugin hooks. + +## Nox session modules + +- `exasol/toolbox/nox/_artifacts.py`: artifact validation, copy, and Sonar + upload sessions. +- `exasol/toolbox/nox/_dependencies.py`: dependency, vulnerability, license, + and SBOM sessions. +- `exasol/toolbox/nox/_documentation.py`: documentation, links, and changelog + sessions. +- `exasol/toolbox/nox/_format.py`: format fix and check sessions. +- `exasol/toolbox/nox/_lint.py`: code, typing, and security lint sessions. +- `exasol/toolbox/nox/_matrix.py`: matrix output sessions for CI. +- `exasol/toolbox/nox/_package.py`: package validation. +- `exasol/toolbox/nox/_release.py`: release preparation, update, and trigger + sessions. +- `exasol/toolbox/nox/_skills.py`: packaged-skill validation and installation + sessions. +- `exasol/toolbox/nox/_test.py`: unit, integration, and coverage sessions. +- `exasol/toolbox/nox/_workflow.py`: workflow check, generation, and audit + sessions. + +## Nox support files + +- `exasol/toolbox/nox/_shared.py`: historical shared helpers. Put new reusable + logic below `exasol/toolbox/util/` when more than one session needs it. +- `exasol/toolbox/nox/tasks.py`: exported session list. Import new session + modules here so downstream `noxfile.py` files can import the standard tasks. + Implement sessions in dedicated `_*.py` modules. + +## Packaged and repository-local skills + +- `.agents/skills/`: repository-local maintenance skills. +- `exasol/toolbox/skills/`: skills packaged in the wheel and installed into + downstream projects. +- `exasol/toolbox/util/skill_eval.py`: evaluation-case models. +- `exasol/toolbox/util/skills.py`: skill discovery, validation, and + installation helpers. +- `test/resources/skills/`: evaluation cases for packaged skills. +- `test/unit/skills_test.py`: package, installation, and skill-specific tests. +- `test/unit/util/skill_test.py`: shared validation and installation tests. + +## Tools and reusable logic + +- `exasol/toolbox/tools/issue.py`: issue-template CLI. +- `exasol/toolbox/tools/replace_version.py`: version replacement helpers. +- `exasol/toolbox/tools/security.py`: security issue conversion and creation. +- `exasol/toolbox/tools/tbx.py`: CLI root. +- `exasol/toolbox/tools/template.py`: template list, show, diff, install, and + update helpers. +- `exasol/toolbox/util/dependencies/`: dependency audit, licenses, changes, + vulnerability tracking, and updates. +- `exasol/toolbox/util/git.py`: Git helpers. +- `exasol/toolbox/util/release/`: changelog, release notes, and Cookiecutter + version helpers. +- `exasol/toolbox/util/version.py`: version parsing and upgrades. + +## Workflows, documentation, and templates + +- `exasol/toolbox/templates/github/workflows/`: packaged workflow templates. +- `exasol/toolbox/templates/github/`: other packaged GitHub templates and + zizmor configuration. +- `exasol/toolbox/util/workflows/`: workflow rendering, patching, validation, + and custom-workflow extraction. +- `.workflow-patcher.yml`: workflow patch configuration for this repository. +- `.github/workflows/`: generated repository workflows. +- `.github/actions/`: repository GitHub actions. +- `doc/user_guide/`: user tasks and feature documentation. +- `doc/developer_guide/`: maintainer and plugin documentation. +- `doc/api/`: API documentation entry points. +- `doc/changes/`: changelog files. +- `project-template/`: Cookiecutter template for new PTB projects. + +## Tests + +- `test/unit/`: unit tests for PTB behavior. +- `test/integration/`: integration tests. +- `test/integration/project-template/`: generated-project tests. diff --git a/doc/changes/unreleased.md b/doc/changes/unreleased.md index fb4737052..af1189106 100644 --- a/doc/changes/unreleased.md +++ b/doc/changes/unreleased.md @@ -1,3 +1,7 @@ # Unreleased ## Summary + +## Refactoring + +* #988: Split PTB repository maintenance guidance from the packaged skill. diff --git a/doc/developer_guide/agent_skills.rst b/doc/developer_guide/agent_skills.rst index afa65328a..b42810798 100644 --- a/doc/developer_guide/agent_skills.rst +++ b/doc/developer_guide/agent_skills.rst @@ -3,6 +3,18 @@ Testing Agent Skills ==================== +Repository-local maintainer skill +--------------------------------- + +The ``.agents/skills/maintain-ptb`` skill contains source routing and +development rules for maintaining this repository. The ``skills:install`` +session copies skills from ``exasol/toolbox/skills`` and keeps this skill local +to the repository. + +Keep downstream PTB usage guidance in the packaged +``exasol-python-toolbox`` skill. Place PTB implementation paths and repository +maintenance rules in the repository-local maintainer skill. + Packaged Skills --------------- diff --git a/doc/user_guide/features/agent_skills/index.rst b/doc/user_guide/features/agent_skills/index.rst index 55870ff0d..1428db347 100644 --- a/doc/user_guide/features/agent_skills/index.rst +++ b/doc/user_guide/features/agent_skills/index.rst @@ -24,7 +24,9 @@ skill names with this list in mind. docstrings, user-facing documentation, and runtime behavior. * - ``exasol-python-toolbox`` - Guides agents in using PTB setup, Nox sessions, checks, workflows, - updates, releases, and configuration. + updates, releases, and configuration in a consuming project. PTB + repository maintenance guidance stays in the repository-local + ``maintain-ptb`` skill. Run the validation with: diff --git a/exasol/toolbox/skills/exasol-python-toolbox/SKILL.md b/exasol/toolbox/skills/exasol-python-toolbox/SKILL.md index 523e54a50..2aa85eebc 100644 --- a/exasol/toolbox/skills/exasol-python-toolbox/SKILL.md +++ b/exasol/toolbox/skills/exasol-python-toolbox/SKILL.md @@ -1,65 +1,54 @@ --- # Generated and maintained by the exasol-toolbox. name: exasol-python-toolbox -description: Use this skill in Exasol Python projects that use exasol-toolbox/PTB. Use it for PTB setup, nox sessions, code checks, GitHub workflows, updates, releases, and PTB configuration. Use it when an agent must not replace PTB automation. +description: "Use Exasol Python Toolbox (PTB) in projects that consume exasol-toolbox. Covers PTB setup, Poetry, PROJECT_CONFIG, Nox sessions, code checks, GitHub workflows, dependency updates, and releases." --- # Exasol Python Toolbox -Use PTB as the task interface for Exasol Python repositories. Use the nox +Use PTB as the task interface for Exasol Python projects. Use the Nox sessions, configuration, templates, and hooks from the installed -`exasol-toolbox` package. Do not replace them with manual commands. Use direct -tool commands only to isolate a failure. +`exasol-toolbox` package as the primary task interface. Reserve direct tool +commands for fault isolation. -Use controlled technical English. Use short sentences. Put one instruction in -one sentence when possible. Use the same term for the same item. +## Project detection -## Operating rules - -1. Confirm that the project uses PTB before you act: - - `pyproject.toml` contains a dependency on `exasol-toolbox`. - - `noxfile.py` imports from `exasol.toolbox.nox.tasks`. - - `noxconfig.py` defines `PROJECT_CONFIG`. -2. Run commands with Poetry. If the project gives a different command, use it. -3. Use `references/nox-sessions.md` for session names and command syntax. -4. Before you edit generated workflow files, use PTB workflow sessions, - `.workflow-patcher.yml`, `PROJECT_CONFIG`, or PTB hooks. -5. Do not run Black, isort, Ruff, Pylint, Mypy, Pytest, Coverage, Sphinx, - Poetry build, Twine, or zizmor directly when a PTB nox session does the same - work. Use direct tool commands only for fault isolation. +Confirm that `pyproject.toml` depends on `exasol-toolbox`, `noxfile.py` imports +from `exasol.toolbox.nox.tasks`, and `noxconfig.py` defines `PROJECT_CONFIG`. ## Task routing -Read only the reference that the task needs: +Select the reference that matches the task: -- Source files and resource files for exact PTB operation: - `references/source-routing.md` - Setup, code changes, CI fixes, releases, PTB updates, dependency updates, and workflow maintenance: `references/common-workflows.md` - Nox session names, arguments, outputs, and limits: `references/nox-sessions.md` -- Coding rules, PTB design rules, and rules for PTB extension: +- Project coding and extension rules for a project that uses PTB: `references/coding-guidelines.md` -## Source rule +## Operating rules -The skill does not copy PTB source code. Source copies can become old. Use this -skill to find the correct file. Read the file from the repository before you -change or explain exact PTB operation. +- Run commands with Poetry or the command specified by the project. +- Use the matching PTB Nox session for formatting, linting, testing, + documentation, packaging, and workflow tasks. Reserve direct tool invocation + for fault isolation. +- Change generated workflow behavior through PTB workflow sessions, + `.workflow-patcher.yml`, `PROJECT_CONFIG`, or PTB hooks. ## Release safety -`release:trigger` creates git tags. It pushes the tags. Run it only when the -user asks you to trigger a release. +`release:trigger` creates and pushes git tags. Require an explicit user request +before running it. Before you run `release:trigger`: 1. Confirm that `release:prepare` ran and its PR is merged. 2. Confirm that the current branch is the default branch. 3. Confirm that the current branch is at the latest remote commit. -4. Confirm that the current project version has no git tag and no GitHub - release. -5. Confirm that the current project version is newer than the latest release, - unless the user confirms a different release plan. +4. Confirm that the current project version remains untagged and unpublished + as a GitHub release. +5. Confirm that the current project version is newer than the latest release. + Follow a different release plan after the user explicitly confirms it. Use `references/common-workflows.md` for the release workflow. diff --git a/exasol/toolbox/skills/exasol-python-toolbox/references/coding-guidelines.md b/exasol/toolbox/skills/exasol-python-toolbox/references/coding-guidelines.md index 9d66d84d1..d37800c90 100644 --- a/exasol/toolbox/skills/exasol-python-toolbox/references/coding-guidelines.md +++ b/exasol/toolbox/skills/exasol-python-toolbox/references/coding-guidelines.md @@ -1,75 +1,27 @@ -# Coding Guidelines for PTB Work +# Guidelines for Projects That Use PTB PTB is a development dependency. PTB is also a task interface. Keep project -automation aligned with PTB conventions. Change the convention only if the -project has a clear reason. +automation aligned with PTB conventions. Change a convention when the project +has a clear reason. -Use controlled technical English in user-facing text. Use short sentences. Put -one instruction in one sentence when possible. Use consistent terms. +## Configuration and extension -## Sources to read - -- `doc/design.rst`: PTB design rules and task boundaries. -- `doc/user_guide/getting_started.rst`: setup and integration. -- `doc/user_guide/features/formatting_code/index.rst`: format tools and format - sessions. -- `doc/user_guide/features/creating_a_release.rst`: release procedure. -- `doc/user_guide/features/git_hooks/index.rst`: pre-commit and pre-push - hooks. -- `doc/user_guide/features/github_workflows/index.rst`: workflow types, - maintained workflows, and custom workflows. -- `doc/user_guide/features/github_workflows/create_and_update.rst`: workflow - generation, update, and check commands. -- `doc/user_guide/features/github_workflows/workflow_patcher.rst`: supported - `.workflow-patcher.yml` configuration. -- `doc/user_guide/features/github_workflows/workflow_variables.rst`: workflow - template values, custom workflow secrets, permissions, and matrix behavior. -- PEP 8: Python style guidance: - `https://peps.python.org/pep-0008/` -- Google Python Style Guide: Python coding guidance: - `https://google.github.io/styleguide/pyguide.html` -- Exasol Python styleguide tooling reference: - `https://exasol.github.io/python-styleguide/guides/tooling.html`. Use it as - a PTB tooling reference. Do not use it as the final official Exasol coding - guideline until the team defines and maintains one. - -## Design rules to keep - -- Treat PTB as development tooling. -- Do not import PTB from production package code. -- Use conventions first. -- Add configuration only when a convention is not sufficient. +- Keep PTB imports in development code. - Use `pyproject.toml` for static tool configuration. - Use `noxconfig.py` and `PROJECT_CONFIG` for dynamic project configuration. - Use plugin hooks or PTB extension points for project-specific work. -- Make project-specific work operate with standard sessions. - Keep GitHub workflows as orchestration. -- Put shared task logic in Python functions or nox sessions. -- Do not put shared task logic directly in workflow YAML. -- Do not make nox sessions notify other nox sessions for shared task logic. -- Put shared nox logic in functions that receive the nox `Session`. -- Add a PTB feature only when a real project needs it. -- Move logic into PTB when more than one project needs it. - -## Code change rules - -Use PTB sessions to format and validate code. - -When you change public operation, update the related tests. For almost all -non-automated changes, add an entry to `doc/changes/unreleased.md`. The usual -exception is a dependency update PR that CI creates automatically. - -For workflow-template changes, check generated workflows. Generate workflows -only when you intend to change them. Use `nox-sessions.md` for command syntax. -## Project-specific differences +## Project-specific behavior -If a standard PTB session is not correct for a project: +When a project needs behavior beyond a standard PTB session: 1. Check whether existing `BaseConfig` or `PROJECT_CONFIG` fields solve the issue. 2. Check whether a PTB plugin hook applies. 3. Use `.workflow-patcher.yml` for supported workflow changes. -4. Use a local nox override only as a short-term migration step. -5. If multiple projects need the same change, consider a PTB template, +4. Keep a local Nox override scoped to a short-term migration. Create a project + issue to replace it with configuration, a plugin hook, or a PTB extension + point. +5. When multiple projects need the same change, consider a PTB template, configuration field, or hook. diff --git a/exasol/toolbox/skills/exasol-python-toolbox/references/common-workflows.md b/exasol/toolbox/skills/exasol-python-toolbox/references/common-workflows.md index f08b2569e..bcdbfd3e4 100644 --- a/exasol/toolbox/skills/exasol-python-toolbox/references/common-workflows.md +++ b/exasol/toolbox/skills/exasol-python-toolbox/references/common-workflows.md @@ -33,24 +33,17 @@ For an existing project: 5. Move tool configuration to `pyproject.toml` where PTB expects it. 6. Run `poetry install`. 7. List the available nox sessions. -8. Add optional integrations only when the project needs them. Examples are +8. Add optional integrations that the project needs. Examples are pre-commit hooks, documentation, Sonar, and GitHub workflows. -If a project cannot use a PTB session without changes, use a local override -only as a short-term migration step. For a permanent solution, use -configuration, plugin hooks, or PTB extension points. -When you add a temporary local override, create an issue in the project to -replace it with configuration, a plugin hook, or a PTB extension point later. - ## Make a daily code change 1. Read `noxconfig.py`. 2. Read the related tool sections in `pyproject.toml`. 3. Make the requested code change, document change, or configuration change. 4. Run the smallest PTB session that checks the change. -5. Run `project:check` when the change affects shared operation. -6. Run `project:check` when the change affects release readiness. -7. Run `project:check` when the change affects CI operation. +5. Run `project:check` when the change affects shared operation, release + readiness, or CI. When you remove or rename a documentation file, update each Sphinx `toctree` that points to it. Then run `docs:build`. @@ -70,8 +63,7 @@ push. Run the PTB formatter first. Then run the checks that match the failure. Use `nox-sessions.md` for the exact session commands. -Do not adjust code manually to imitate Black, isort, or Ruff. Let PTB run these -tools. To exclude a Python file or directory, use +To exclude a Python file or directory, use `PROJECT_CONFIG.add_to_excluded_python_paths` in `noxconfig.py`. ## Prepare a release @@ -81,20 +73,22 @@ Prepare a release with `release:prepare`. This session does these actions: 1. It updates the version. -2. It creates a release branch and sets it as the current Git branch unless you - use `--no-branch` or `--no-add`. +2. It creates a release branch and sets it as the current Git branch by + default. The `--no-branch` and `--no-add` flags keep the current branch. 3. It moves content from `doc/changes/unreleased.md` to a versioned changes file. 4. It updates `doc/changes/changelog.md`. 5. It runs configured release hooks. -6. It commits the changes if you do not use `--no-add`. -7. It opens a PR if you do not use `--no-pr`. +6. It commits the changes by default. The `--no-add` flag leaves the changes + for manual review and commit. +7. It opens a PR by default. The `--no-pr` flag leaves PR creation as a later + step. Useful flags: -- `--no-branch`: Do not create a release branch and do not set it as current. -- `--no-add`: Do not add or commit changes. This also prevents release branch - creation. -- `--no-pr`: Do not create a pull request. +- `--no-branch`: Keep the current branch. +- `--no-add`: Leave changes unstaged and uncommitted, and keep the current + branch. +- `--no-pr`: Leave pull-request creation as a later step. If dependencies change after release preparation, update the versioned changes file with `release:update`. @@ -113,8 +107,8 @@ When you update `exasol-toolbox` in a project: 2. Check the `exasol-toolbox` version range in `pyproject.toml`. 3. Update the dependency with Poetry. Example: `poetry update exasol-toolbox` -4. If Poetry does not update PTB, adjust the version range intentionally. This - is usually necessary for a new PTB major version. +4. When the current version range keeps the existing PTB version, adjust the + range intentionally. This is usually necessary for a new PTB major version. 5. Generate or check PTB-managed workflows. 6. Run necessary validation sessions. 7. Update `doc/changes/unreleased.md` when the project requires a changelog @@ -127,13 +121,12 @@ sessions. PTB has two workflow groups: -- PTB-provided workflows: Do not edit generated files by hand. Use - `.workflow-patcher.yml` for supported project-specific changes. Use - `PROJECT_CONFIG`, a PTB template, or a hook for shared behavior. Then run - `workflow:generate` and `workflow:check`. +- PTB-provided workflows: Express project-specific changes through + `.workflow-patcher.yml`. Use `PROJECT_CONFIG`, a PTB template, or a hook for + shared behavior. Then run `workflow:generate` and `workflow:check`. - Custom workflows: The project owns these files. Edit the custom file directly. Prefer workflow extension files that PTB can call from a PTB-provided - workflow. Use a separate workflow trigger only when the project owns the merge + workflow. Use a separate workflow trigger when the project owns the merge protection decision for that workflow. Put GitHub `permissions` in the jobs that need them. Declare reusable-workflow secrets under `on.workflow_call.secrets`. diff --git a/exasol/toolbox/skills/exasol-python-toolbox/references/nox-sessions.md b/exasol/toolbox/skills/exasol-python-toolbox/references/nox-sessions.md index 063b45d39..78ee89526 100644 --- a/exasol/toolbox/skills/exasol-python-toolbox/references/nox-sessions.md +++ b/exasol/toolbox/skills/exasol-python-toolbox/references/nox-sessions.md @@ -60,13 +60,13 @@ poetry run -- nox -s skills:install | `docs:clean` | Remove generated documentation. | It deletes `.html-documentation`. | | `links:list` | List documentation links. | It uses Sphinx linkcheck. It ignores link failures. | | `links:check` | Validate documentation links. | It can write JSON output with `-- -o `. | -| `changelog:updated` | Check that the changelog changed. | It fails if `doc/changes` did not change when compared with `origin/main`. | +| `changelog:updated` | Check that the changelog changed. | It compares `doc/changes` with `origin/main` and requires a difference. | ## Release sessions | Session | Use | Notes | | --- | --- | --- | -| `release:prepare` | Prepare a release PR. | It requires `-- --type major`, `minor`, or `patch`. It creates a branch, commit, and PR if flags do not disable these actions. | +| `release:prepare` | Prepare a release PR. | It requires `-- --type major`, `minor`, or `patch`. It creates a branch, commit, and PR by default; flags support manual handling. | | `release:update` | Update a prepared release changelog. | It updates the latest versioned changelog after dependency changes. | | `release:trigger` | Trigger a release from the default branch. | It creates and pushes git tags. | diff --git a/exasol/toolbox/skills/exasol-python-toolbox/references/source-routing.md b/exasol/toolbox/skills/exasol-python-toolbox/references/source-routing.md deleted file mode 100644 index 185c714d6..000000000 --- a/exasol/toolbox/skills/exasol-python-toolbox/references/source-routing.md +++ /dev/null @@ -1,98 +0,0 @@ -# Source Routing - -Use this reference to find the source file for exact PTB operation. -Read the source file before you change code. -Read the source file before you explain a detailed rule. - -## Project entry points - -- `pyproject.toml`: package data, dependencies, tool configuration, and - packaged resources. -- `noxfile.py`: local nox entry point. -- `noxconfig.py`: local `PROJECT_CONFIG` and release hooks. -- `README.rst`: project overview. -- `doc/design.rst`: PTB design rules. - -## PTB configuration - -- `exasol/toolbox/config.py`: `BaseConfig`, computed configuration fields, - supported versions, paths, workflow variables, and plugin validation. -- `exasol/toolbox/nox/plugin.py`: nox plugin hooks. - -## PTB nox sessions - -- `exasol/toolbox/nox/_artifacts.py`: artifact validation, artifact copy, and - Sonar upload sessions. -- `exasol/toolbox/nox/_dependencies.py`: dependency audit, license, - vulnerability, and SBOM sessions. -- `exasol/toolbox/nox/_documentation.py`: documentation, link check, and - changelog sessions. -- `exasol/toolbox/nox/_format.py`: `format:fix` and `format:check`. -- `exasol/toolbox/nox/_lint.py`: `lint:code`, `lint:typing`, and - `lint:security`. -- `exasol/toolbox/nox/_skills.py`: packaged skill validation and installation - implementations. -- `exasol/toolbox/nox/_matrix.py`: matrix output sessions for CI usage. -- `exasol/toolbox/nox/_package.py`: package validation. -- `exasol/toolbox/nox/_release.py`: release preparation, release update, and - release trigger sessions. -- `exasol/toolbox/nox/_test.py`: `test:unit`, `test:integration`, and - `test:coverage`. -- `exasol/toolbox/nox/_workflow.py`: workflow check, generation, and audit - sessions. - -## PTB nox support files - -- `exasol/toolbox/nox/_shared.py`: old shared nox helpers. Prefer - `exasol/toolbox/util/` for new code that more than one session uses. -- `exasol/toolbox/nox/tasks.py`: exported nox session list. Import new nox - session modules here so projects that use PTB can import them with - `from exasol.toolbox.nox.tasks import *`. Do not add new session code here. - -## PTB tools - -Do not add new functions under `exasol/toolbox/tools/`. Put reusable code in -`exasol/toolbox/util/`. Prefer a nox session for new user-facing operations. - -- `exasol/toolbox/tools/issue.py`: issue template CLI. -- `exasol/toolbox/tools/replace_version.py`: version replacement helpers. -- `exasol/toolbox/tools/security.py`: security issue conversion and creation. -- `exasol/toolbox/tools/tbx.py`: CLI root. -- `exasol/toolbox/tools/template.py`: template list, show, diff, install, and - update helpers. - -## Workflow templates and helpers - -- `exasol/toolbox/templates/github/workflows/`: packaged GitHub workflow - templates. -- `exasol/toolbox/templates/github/`: packaged GitHub templates and zizmor - configuration. -- `exasol/toolbox/util/workflows/`: workflow rendering, patching, validation, - and custom workflow extraction. -- `.workflow-patcher.yml`: PTB workflow patch configuration for this repository. -- `.github/workflows/`: generated repository workflows. -- `.github/actions/`: repository GitHub actions. - -## Release and dependency helpers - -- `exasol/toolbox/util/dependencies/`: dependency audit, license report, - dependency change, vulnerability tracking, and dependency update helpers. -- `exasol/toolbox/util/git.py`: git helper functions. -- `exasol/toolbox/util/release/`: changelog, release notes, and Cookiecutter - version helpers. -- `exasol/toolbox/util/version.py`: version parsing and version upgrade logic. - -## Documentation and project template - -- `doc/user_guide/`: user tasks and feature documentation. -- `doc/developer_guide/`: developer and plugin documentation. -- `doc/api/`: API documentation entry points. -- `doc/changes/`: changelog files. -- `project-template/`: Cookiecutter template for new PTB projects. - -## Tests - -- `test/unit/`: unit tests for PTB operation. -- `test/integration/`: integration tests. -- `test/integration/project-template/`: tests for the Cookiecutter project - template. diff --git a/test/integration/project-template/nox_test.py b/test/integration/project-template/nox_test.py index 35da03ced..d3e8618da 100644 --- a/test/integration/project-template/nox_test.py +++ b/test/integration/project-template/nox_test.py @@ -2,7 +2,7 @@ EXPECTED_PACKAGED_SKILL_FILE_COUNTS = { "api-contract-audit": 1, - "exasol-python-toolbox": 5, + "exasol-python-toolbox": 4, } EXPECTED_NOX_SESSIONS = { "format:fix", diff --git a/test/resources/skills/exasol-python-toolbox/eval_cases.yml b/test/resources/skills/exasol-python-toolbox/eval_cases.yml index 42b2d0e68..02778b798 100644 --- a/test/resources/skills/exasol-python-toolbox/eval_cases.yml +++ b/test/resources/skills/exasol-python-toolbox/eval_cases.yml @@ -99,14 +99,16 @@ cases: - "ignore migration notes" - "skip validation" - - id: "exact-source-behavior" - category: "source-routing" - prompt: "I need exact behavior for release preparation. Tell me which source file to read." + - id: "customize-project-behavior" + category: "customization" + prompt: "A standard PTB session does not fit one project's needs. Tell me how to customize the project safely." expected: must_include: - - "source-routing.md" - - "exasol/toolbox/nox/_release.py" - - "read the source file" + - "PROJECT_CONFIG" + - "plugin hook" + - ".workflow-patcher.yml" + - "local nox override" + - "short-term" must_not_include: - - "guess" - - "copy PTB source code" + - "edit generated workflow directly" + - "copy PTB implementation" diff --git a/test/unit/skills_test.py b/test/unit/skills_test.py index 29178ff99..646acc5c2 100644 --- a/test/unit/skills_test.py +++ b/test/unit/skills_test.py @@ -16,12 +16,13 @@ PROJECT_ROOT = Path(__file__).parents[2] SKILL = get_skill_path(PTB_SKILL_NAME) +MAINTAINER_SKILL_NAME = "maintain-ptb" +MAINTAINER_SKILL = PROJECT_ROOT / ".agents" / "skills" / MAINTAINER_SKILL_NAME SKILL_FILES = [ "SKILL.md", "references/coding-guidelines.md", "references/common-workflows.md", "references/nox-sessions.md", - "references/source-routing.md", ] @@ -47,9 +48,8 @@ def _skills_with_eval_cases() -> list[str]: def test_ptb_skill_resources_are_available(): skill_files = get_skill_files(PTB_SKILL_NAME) - for expected in SKILL_FILES: - assert expected in skill_files - assert skill_files[expected].is_file() + assert set(skill_files) == set(SKILL_FILES) + assert all(path.is_file() for path in skill_files.values()) def test_ptb_skill_can_be_installed(tmp_path): @@ -60,6 +60,30 @@ def test_ptb_skill_can_be_installed(tmp_path): assert (installed / expected).is_file() +def test_ptb_maintainer_skill_is_repository_local(): + expected_files = { + "SKILL.md", + "references/coding-guidelines.md", + "references/source-routing.md", + } + actual_files = { + str(path.relative_to(MAINTAINER_SKILL)) + for path in MAINTAINER_SKILL.rglob("*") + if path.is_file() + } + + assert actual_files == expected_files + assert MAINTAINER_SKILL_NAME not in get_packaged_skill_names() + + +def test_ptb_maintainer_skill_frontmatter_is_complete(): + content = (MAINTAINER_SKILL / "SKILL.md").read_text(encoding="utf-8") + frontmatter = content.split("---", maxsplit=2)[1] + + assert f"name: {MAINTAINER_SKILL_NAME}" in frontmatter + assert "Maintain and extend the Exasol Python Toolbox repository" in frontmatter + + @pytest.mark.parametrize("skill_name", get_packaged_skill_names()) def test_packaged_skills_can_be_installed(skill_name, tmp_path): installed = install_skill(skill_name, tmp_path) @@ -105,7 +129,10 @@ def test_ptb_skill_frontmatter_is_complete(): frontmatter = content.split("---", maxsplit=2)[1] assert "name: exasol-python-toolbox" in frontmatter - assert "description: Use this skill in Exasol Python projects" in frontmatter + assert ( + "Use Exasol Python Toolbox (PTB) in projects that consume exasol-toolbox" + in frontmatter + ) assert "[TODO" not in content @@ -134,7 +161,7 @@ def test_ptb_skill_eval_cases_cover_ticket_scope(): "release", "update", "workflow", - "source-routing", + "customization", }.issubset(categories) From 49f381960d9b1a5f79b7360fcbd59d5374babab2 Mon Sep 17 00:00:00 2001 From: jana-selva Date: Fri, 30 Oct 2026 11:30:00 +0530 Subject: [PATCH 2/2] Update generated workflows for PTB v12 --- .github/workflows/build-and-publish.yml | 2 +- .github/workflows/check-release-tag.yml | 2 +- .github/workflows/checks.yml | 18 +++++++++--------- .github/workflows/dependency-update.yml | 2 +- .github/workflows/fast-tests.yml | 2 +- .github/workflows/gh-pages.yml | 2 +- .github/workflows/matrix.yml | 2 +- .github/workflows/report.yml | 2 +- 8 files changed, 16 insertions(+), 16 deletions(-) diff --git a/.github/workflows/build-and-publish.yml b/.github/workflows/build-and-publish.yml index e4f618dbd..4a9a30f57 100644 --- a/.github/workflows/build-and-publish.yml +++ b/.github/workflows/build-and-publish.yml @@ -22,7 +22,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v11 + uses: exasol/python-toolbox/.github/actions/python-environment@v12 with: python-version: "3.11" poetry-version: "2.3.0" diff --git a/.github/workflows/check-release-tag.yml b/.github/workflows/check-release-tag.yml index 840f71e87..a6297b4c7 100644 --- a/.github/workflows/check-release-tag.yml +++ b/.github/workflows/check-release-tag.yml @@ -20,7 +20,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v11 + uses: exasol/python-toolbox/.github/actions/python-environment@v12 with: python-version: "3.11" poetry-version: "2.3.0" diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index 56c2972ab..dcdb0dca1 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -19,7 +19,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v11 + uses: exasol/python-toolbox/.github/actions/python-environment@v12 with: python-version: "3.11" poetry-version: "2.3.0" @@ -47,7 +47,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v11 + uses: exasol/python-toolbox/.github/actions/python-environment@v12 with: python-version: "3.11" poetry-version: "2.3.0" @@ -74,7 +74,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v11 + uses: exasol/python-toolbox/.github/actions/python-environment@v12 with: python-version: ${{ matrix.python-versions }} poetry-version: "2.3.0" @@ -112,7 +112,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v11 + uses: exasol/python-toolbox/.github/actions/python-environment@v12 with: python-version: ${{ matrix.python-versions }} poetry-version: "2.3.0" @@ -140,7 +140,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v11 + uses: exasol/python-toolbox/.github/actions/python-environment@v12 with: python-version: ${{ matrix.python-versions }} poetry-version: "2.3.0" @@ -172,7 +172,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v11 + uses: exasol/python-toolbox/.github/actions/python-environment@v12 with: python-version: "3.11" poetry-version: "2.3.0" @@ -195,7 +195,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v11 + uses: exasol/python-toolbox/.github/actions/python-environment@v12 with: python-version: "3.11" poetry-version: "2.3.0" @@ -218,7 +218,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v11 + uses: exasol/python-toolbox/.github/actions/python-environment@v12 with: python-version: "3.11" poetry-version: "2.3.0" @@ -241,7 +241,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v11 + uses: exasol/python-toolbox/.github/actions/python-environment@v12 with: python-version: "3.11" poetry-version: "2.3.0" diff --git a/.github/workflows/dependency-update.yml b/.github/workflows/dependency-update.yml index b2e095fdc..1d443bb30 100644 --- a/.github/workflows/dependency-update.yml +++ b/.github/workflows/dependency-update.yml @@ -34,7 +34,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v11 + uses: exasol/python-toolbox/.github/actions/python-environment@v12 with: python-version: "3.11" poetry-version: "2.3.0" diff --git a/.github/workflows/fast-tests.yml b/.github/workflows/fast-tests.yml index 1fc01cf83..a5999cf36 100644 --- a/.github/workflows/fast-tests.yml +++ b/.github/workflows/fast-tests.yml @@ -24,7 +24,7 @@ jobs: fetch-depth: 0 - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v11 + uses: exasol/python-toolbox/.github/actions/python-environment@v12 with: python-version: ${{ matrix.python-versions }} poetry-version: "2.3.0" diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 6cf1c9f4b..ff7cf6298 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -21,7 +21,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v11 + uses: exasol/python-toolbox/.github/actions/python-environment@v12 with: python-version: "3.11" poetry-version: "2.3.0" diff --git a/.github/workflows/matrix.yml b/.github/workflows/matrix.yml index 56bd1c3d5..374ec311f 100644 --- a/.github/workflows/matrix.yml +++ b/.github/workflows/matrix.yml @@ -27,7 +27,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v11 + uses: exasol/python-toolbox/.github/actions/python-environment@v12 with: python-version: "3.11" poetry-version: "2.3.0" diff --git a/.github/workflows/report.yml b/.github/workflows/report.yml index dfd08c55c..c7fd8d5c5 100644 --- a/.github/workflows/report.yml +++ b/.github/workflows/report.yml @@ -23,7 +23,7 @@ jobs: - name: Set up Python & Poetry Environment id: set-up-python-and-poetry-environment - uses: exasol/python-toolbox/.github/actions/python-environment@v11 + uses: exasol/python-toolbox/.github/actions/python-environment@v12 with: python-version: "3.11" poetry-version: "2.3.0"