diff --git a/README.md b/README.md index 4093eda..b31a16b 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,9 @@ **QGIS plugin name:** IB-Tool-Data-Wizard · **Status:** experimental · **Version:** 0.1 -Data Wizard is a companion QGIS plugin to **[IBTool](https://github.com/IB-Tool/IB-Tool-3)**. +Data Wizard is a companion QGIS plugin to **[IB-Tool 3](https://github.com/IB-Tool/IB-Tool-3)**. It automates turning raw ATKIS Basis-DLM data into the `HU`/`RN`/`Aux` -GeoPackages IBTool needs — a workflow that previously had to be done by +GeoPackages IB-Tool 3 needs — a workflow that previously had to be done by hand in QGIS. Given a folder of raw ATKIS shapefiles and a separately chosen @@ -18,15 +18,15 @@ building-footprint file, Data Wizard: input automatically, - optionally clips everything to a study-area polygon, - maps and merges the raw layers into `HU.gpkg`, `RN.gpkg`, and - `AUX_L.gpkg` following IBTool's fixed mapping rules, + `AUX_L.gpkg` following IB-Tool 3's fixed mapping rules, - detects (or lets you pick) the building function-code column if it isn't already named `fkt`, `gfkzshh`, or `funktion`, and copies it into a correctly named column. **Full documentation:** [`docs/README.md`](docs/README.md) — inputs, usage, the exact mapping rules, architecture, and cross-references to -IBTool's own documentation (target data format, the manual workflow this -plugin automates, IBTool's usage). +IB-Tool 3's own documentation (target data format, the manual workflow this +plugin automates, IB-Tool 3's usage). ## Installation @@ -41,11 +41,11 @@ Plugins**: | macOS | `~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins` | The plugin then appears under **Erweiterungen → IB-Tool → Data Wizard** -(grouped with IBTool itself). +(grouped with IB-Tool 3 itself). ## Development -CI runs the same two workflows as IBTool and ibtoolpartion — a Docker-based +CI runs the same two workflows as IB-Tool 3 and ibtoolpartion — a Docker-based test suite (`ci.yml`) and lint/security/structure validation (`qgis-plugin-ci.yml`). See [`docs/contributing.md`](docs/contributing.md) for the full setup, local test commands, and release process. diff --git a/ai/core/architecture-guidelines.md b/ai/core/architecture-guidelines.md index a5ba5ce..1957666 100644 --- a/ai/core/architecture-guidelines.md +++ b/ai/core/architecture-guidelines.md @@ -5,7 +5,7 @@ Guidelines for architectural decisions in the data_wizard project. ## Module Layout data_wizard is intentionally a single-module plugin, not a package-of-packages -like IB-Tool-3: +like IB-Tool 3: - **`processor.py`** - all ATKIS transformation logic, no QGIS UI or `iface` access. Pure function pipeline: load → reproject/clip → transform → write. @@ -59,7 +59,7 @@ still proportionate to this plugin's scope. (`FUNCTION_CODE_PATTERN`, not an inline regex string) - **Pragmatic refactoring**: `processor.py` is ~430 LOC across 12 functions - this is proportionate to the plugin's scope; do not split it into a - package until it meaningfully grows beyond the ATKIS Basis-DLM → IBTool + package until it meaningfully grows beyond the ATKIS Basis-DLM → IB-Tool 3 input pipeline it currently implements ## Testing Implications diff --git a/ai/core/constraints.md b/ai/core/constraints.md index 3c55292..d3f067a 100644 --- a/ai/core/constraints.md +++ b/ai/core/constraints.md @@ -7,13 +7,13 @@ see [release-conventions.md](release-conventions.md). ## Language -> **Deviation from IB-Tool-3:** IB-Tool-3's own `ai/core/constraints.md` +> **Deviation from IB-Tool 3:** IB-Tool 3's own `ai/core/constraints.md` > mandates English for all code comments/docstrings, with German reserved for > UI strings and end-user log output. `processor.py` in this repository does > not follow that split - its docstrings, comments, and `log()` messages are > German throughout, while identifiers are English. This is the actual, > current convention here, not an oversight to silently "correct" by copying -> IB-Tool-3's rule - see the Testplan-data_wizard-ibtoolpartion.md +> IB-Tool 3's rule - see the Testplan-data_wizard-ibtoolpartion.md > "Nebenbefund #4" note, which flags the inconsistency across the three > plugins as a separate decision to make deliberately, not as part of adding > tests/docs. The table below documents what this repository actually does. @@ -23,7 +23,7 @@ see [release-conventions.md](release-conventions.md). | Code identifiers (function/class/variable names) | **English** | `process_atkis`, `_reproject_if_needed`, `target_crs` | | `processor.py` docstrings, comments, `log()` messages | **German** (established convention - do not silently rewrite to English) | `"""Reprojiziert layer nach target_crs..."""` | | `data_wizard.py`, `data_wizard_dialog.py` | **English** (already English throughout) | | -| Test files (`test/`) | **English** (docstrings, comments, assertions) | matches this repo's tests and IB-Tool-3's convention | +| Test files (`test/`) | **English** (docstrings, comments, assertions) | matches this repo's tests and IB-Tool 3's convention | | Developer documentation (`ai/`, `docs/`) | **English** | All markdown files for AI/developer context | | Commit messages, CHANGELOG (technical) | **English** | | | UI strings (via `QCoreApplication.translate()`) | **English** source string, translated via `i18n/*.ts` (German provided) | Dialog labels, message bar text | diff --git a/ai/core/naming-conventions.md b/ai/core/naming-conventions.md index 8a0c582..35d2e1f 100644 --- a/ai/core/naming-conventions.md +++ b/ai/core/naming-conventions.md @@ -54,7 +54,7 @@ All other terms must be spelled out. | Test infrastructure | `snake_case.py` | `layer_factories.py`, `utilities.py` | | Configuration | `snake_case.*` | `pytest.ini`, `test_config.ini` | | Documentation | `kebab-case.md` | `test-strategy.md`, `qgis-api-rules.md` | -| Output GeoPackages | `UPPER_SNAKE_CASE.gpkg` (fixed contract with IBTool) | `HU.gpkg`, `RN.gpkg`, `AUX_L.gpkg` | +| Output GeoPackages | `UPPER_SNAKE_CASE.gpkg` (fixed contract with IB-Tool 3) | `HU.gpkg`, `RN.gpkg`, `AUX_L.gpkg` | ## Parameter Names diff --git a/ai/core/release-conventions.md b/ai/core/release-conventions.md index 574b825..a41872d 100644 --- a/ai/core/release-conventions.md +++ b/ai/core/release-conventions.md @@ -2,8 +2,8 @@ These rules are binding for all code changes. -Mirrors IBTool's own `ai/core/release-conventions.md` (the canonical version, -see [IB-Tool-3](https://github.com/IB-Tool/IB-Tool-3/blob/master/ai/core/release-conventions.md)), +Mirrors IB-Tool 3's own `ai/core/release-conventions.md` (the canonical version, +see [IB-Tool 3](https://github.com/IB-Tool/IB-Tool-3/blob/master/ai/core/release-conventions.md)), adapted for this plugin's folder name and repository. --- diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 8bcf443..f5bccdd 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -10,11 +10,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased ### Added -- `Dockerfile`, `ci/qgis_plugin_validate.py`, `scripts/create_release_zip.py` — Docker-based test execution and release ZIP building, mirroring IBTool's and ibtoolpartion's setup. +- `Dockerfile`, `ci/qgis_plugin_validate.py`, `scripts/create_release_zip.py` — Docker-based test execution and release ZIP building, mirroring IB-Tool 3's and ibtoolpartion's setup. - `.github/workflows/ci.yml` (Docker-based tests + Codecov coverage) and `qgis-plugin-ci.yml` (flake8, bandit, detect-secrets, structure validation). - `pytest.ini`, `requirements-test.txt`, `.flake8`, `.bandit` — test and lint configuration. - `docs/contributing.md` — development setup, CI/CD pipeline, test structure, and release process, matching the other two IB-Tool plugins. -- `ai/core/release-conventions.md` — release invariants shared with IBTool and ibtoolpartion. +- `ai/core/release-conventions.md` — release invariants shared with IB-Tool 3 and ibtoolpartion. ### Fixed - `metadata.txt`: replaced placeholder `tracker`/`repository`/`homepage` URLs (`http://bugs`, `http://repo`, `http://homepage`) with the actual repository URLs; removed a stray unescaped line that was silently parsed as a bogus `category of the plugin` key; added a `changelog` entry (previously commented out). @@ -25,4 +25,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Initial project structure: plugin entry point, dialog, ATKIS-to-HU/RN/Aux processor, i18n, test scaffold. -- `docs/README.md`: full documentation with cross-references to IBTool's own documentation. +- `docs/README.md`: full documentation with cross-references to IB-Tool 3's own documentation. diff --git a/docs/README.md b/docs/README.md index 081b6d0..b16c828 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,27 +1,27 @@ # Data Wizard — Documentation **Data Wizard** (plugin name in QGIS: *IB-Tool-Data-Wizard*) is a companion -QGIS plugin to **IBTool**. It automates the manual ATKIS-to-input-data -workflow described in IBTool's own tutorial: given a folder of raw ATKIS +QGIS plugin to **IB-Tool 3**. It automates the manual ATKIS-to-input-data +workflow described in IB-Tool 3's own tutorial: given a folder of raw ATKIS Basis-DLM data and a separately supplied building-footprint file, it -produces the `HU`, `RN`, and `Aux` GeoPackages IBTool needs — reprojecting, +produces the `HU`, `RN`, and `Aux` GeoPackages IB-Tool 3 needs — reprojecting, optionally clipping, and mapping/merging the raw layers automatically. This document covers **Data Wizard itself** — installation is out of scope (see [Plugin Installation Paths](#plugin-installation-paths) below for the short version). For everything about the *target* data format, -the underlying manual workflow, and IBTool's own usage, see -[Relationship to IBTool's Documentation](#relationship-to-ibtools-documentation). +the underlying manual workflow, and IB-Tool 3's own usage, see +[Relationship to IB-Tool 3's Documentation](#relationship-to-ib-tool-3s-documentation). --- ## What It Does -Data Wizard automates steps 2–7 of IBTool's data preparation tutorial — +Data Wizard automates steps 2–7 of IB-Tool 3's data preparation tutorial — determining the project CRS, optional clipping to a study area, mapping raw ATKIS layers into `HU`/`RN`/`Aux`, and export as GeoPackage. Only step 1 (downloading the raw data yourself) and step 8 (final validation -via IBTool's own **Check** button) stay outside the plugin. +via IB-Tool 3's own **Check** button) stay outside the plugin. 1. **Project CRS** is fixed from the CRS of `ver01_l.shp` in the source folder. Any other raw layer — including the building-footprint file @@ -32,7 +32,7 @@ via IBTool's own **Check** button) stay outside the plugin. no study area is given, raw layers are processed at their full extent. 3. **Mapping & merging** follows a fixed rule (see [Output Layers](#output-layers) below) — the same rule documented in - IBTool's `data-preparation.md`, now applied automatically instead of by + IB-Tool 3's `data-preparation.md`, now applied automatically instead of by hand in QGIS. 4. **HU function-code field**: if the building file doesn't already carry `fkt`, `gfkzshh`, or `funktion`, the plugin scans its columns for one @@ -62,10 +62,10 @@ via IBTool's own **Check** button) stay outside the plugin. progress and any warnings appear as log messages ("Data Wizard" in **View → Panels → Log Messages**) and in the message bar. 4. On completion, `HU.gpkg`, `RN.gpkg`, and `AUX_L.gpkg` are in the target - folder. Load them into IBTool along with a `Part` layer and (optionally) - a filter file, and run IBTool's own **Check** — see - [IBTool's quickstart.md](https://github.com/IB-Tool/IB-Tool-3/blob/master/docs/quickstart.md) - for that step. Data Wizard does not run IBTool's validation checklist + folder. Load them into IB-Tool 3 along with a `Part` layer and (optionally) + a filter file, and run IB-Tool 3's own **Check** — see + [IB-Tool 3's quickstart.md](https://github.com/IB-Tool/IB-Tool-3/blob/master/docs/quickstart.md) + for that step. Data Wizard does not run IB-Tool 3's validation checklist itself. ## Output Layers @@ -80,14 +80,14 @@ via IBTool's own **Check** button) stay outside the plugin. ## Out of Scope - **`Part` (partitioning layer)** — produced by the sibling plugin - **[IB-Tool (Partitioning)](https://github.com/IB-Tool/ibtoolpartion)**; + **[IB-Tool (Partitioning)](https://github.com/IB-Tool/Partitioning)**; Data Wizard doesn't touch it. - **Filter file** — a separately maintained, largely static file; Data Wizard doesn't touch it. -- **Validation** — Data Wizard does not re-implement IBTool's +- **Validation** — Data Wizard does not re-implement IB-Tool 3's `input-data.md` validation checklist. The one exception is a non-blocking log warning if HU ends up with no function-code field at - all. The authoritative check is IBTool's own **Check** button. + all. The authoritative check is IB-Tool 3's own **Check** button. ## Architecture @@ -99,13 +99,13 @@ via IBTool's own **Check** button) stay outside the plugin. -## Relationship to IBTool's Documentation +## Relationship to IB-Tool 3's Documentation -Data Wizard is a data-preparation front-end **for** IBTool — it doesn't -replace IBTool's own documentation, which remains the authority on the -target data format and on IBTool itself. Both plugins now live in their +Data Wizard is a data-preparation front-end **for** IB-Tool 3 — it doesn't +replace IB-Tool 3's own documentation, which remains the authority on the +target data format and on IB-Tool 3 itself. Both plugins now live in their own GitHub repositories (both private, under the `IB-Tool` organization), -so the links below point at IBTool's repository on GitHub rather than a +so the links below point at IB-Tool 3's repository on GitHub rather than a local sibling folder — following them requires being logged into GitHub with access to that org. @@ -114,16 +114,16 @@ with access to that org. | The exact target specification Data Wizard's output must satisfy (field requirements, geometry types, minimum feature counts, the full validation checklist) | [`input-data.md`](https://github.com/IB-Tool/IB-Tool-3/blob/master/docs/input-data.md) | | The manual workflow this plugin automates (background/rationale for each step) | [`data-preparation.md`](https://github.com/IB-Tool/IB-Tool-3/blob/master/docs/data-preparation.md) | | Where to download raw ATKIS data per German state | [`data-sources.md`](https://github.com/IB-Tool/IB-Tool-3/blob/master/docs/data-sources.md) | -| Running IBTool itself once Data Wizard's outputs are ready | [`quickstart.md`](https://github.com/IB-Tool/IB-Tool-3/blob/master/docs/quickstart.md) | -| How IBTool's algorithm actually works | [`how-it-works.md`](https://github.com/IB-Tool/IB-Tool-3/blob/master/docs/how-it-works.md) | -| IBTool's own code structure | [`plugin-architecture.md`](https://github.com/IB-Tool/IB-Tool-3/blob/master/docs/plugin-architecture.md) | +| Running IB-Tool 3 itself once Data Wizard's outputs are ready | [`quickstart.md`](https://github.com/IB-Tool/IB-Tool-3/blob/master/docs/quickstart.md) | +| How IB-Tool 3's algorithm actually works | [`how-it-works.md`](https://github.com/IB-Tool/IB-Tool-3/blob/master/docs/how-it-works.md) | +| IB-Tool 3's own code structure | [`plugin-architecture.md`](https://github.com/IB-Tool/IB-Tool-3/blob/master/docs/plugin-architecture.md) | ## Plugin Installation Paths -Same as any QGIS plugin — see IBTool's +Same as any QGIS plugin — see IB-Tool 3's [`plugin-architecture.md` → Plugin Installation Paths](https://github.com/IB-Tool/IB-Tool-3/blob/master/docs/plugin-architecture.md#plugin-installation-paths) for the per-OS paths; Data Wizard's own folder name (`data_wizard`) is already a valid Python identifier, so no renaming is needed for QGIS to -load it (unlike IBTool's `IB-Tool-3` → `ibtool` rename requirement). +load it (unlike IB-Tool 3's `IB-Tool-3` → `ibtool` rename requirement). diff --git a/docs/contributing.md b/docs/contributing.md index 922e877..cb27c1b 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -2,12 +2,12 @@ This document covers the development setup, CI/CD pipeline, test structure, and code quality tooling for Data Wizard. -This plugin is a companion to **[IBTool](https://github.com/IB-Tool/IB-Tool-3)** -(the main plugin) and follows the same development conventions as IBTool and -[ibtoolpartion](https://github.com/IB-Tool/ibtoolpartion). For the canonical +This plugin is a companion to **[IB-Tool 3](https://github.com/IB-Tool/IB-Tool-3)** +(the main plugin) and follows the same development conventions as IB-Tool 3 and +[IB-Tool (Partitioning)](https://github.com/IB-Tool/Partitioning). For the canonical description of the CI/test/release approach shared by all three IB-Tool plugins, see -[IBTool's own `docs/contributing.md`](https://github.com/IB-Tool/IB-Tool-3/blob/master/docs/contributing.md). +[IB-Tool 3's own `docs/contributing.md`](https://github.com/IB-Tool/IB-Tool-3/blob/master/docs/contributing.md). This document only covers what differs here. --- @@ -34,7 +34,7 @@ Steps: 4. Strips container-absolute paths from `coverage.xml` 5. Uploads the coverage report to Codecov -The image is a slimmed-down variant of IBTool's own `Dockerfile` — this +The image is a slimmed-down variant of IB-Tool 3's own `Dockerfile` — this plugin has no runtime dependencies beyond QGIS's own processing algorithms (`processing`, `qgis.core`), so `numpy`/`scipy`/`networkx` are not installed. @@ -42,7 +42,7 @@ plugin has no runtime dependencies beyond QGIS's own processing algorithms Test coverage is measured with `pytest-cov` (`.coveragerc` at the repo root: `source = data_wizard, scripts`). The `coverage.xml`/`htmlcov/` files are written by the container into the volume-mounted workspace, with container-absolute paths (`/plugins/data_wizard/`) stripped for portability. -> **No Codecov upload.** Unlike IBTool and ibtoolpartion, this repository does +> **No Codecov upload.** Unlike IB-Tool 3 and ibtoolpartion, this repository does > not have a Codecov project set up (`CODECOV_TOKEN` was never configured, > and the previous Codecov upload step in `ci.yml` could only ever fail with > `fail_ci_if_error: true`). This is a deliberate, documented exclusion — see @@ -124,7 +124,7 @@ git commit --no-verify ## Release Process -Releases are built with `scripts/create_release_zip.py`, mirroring IBTool's +Releases are built with `scripts/create_release_zip.py`, mirroring IB-Tool 3's and ibtoolpartion's release process: ```bash @@ -202,7 +202,7 @@ system Python does not: | File | Content | |------|---------| -| [`docs/README.md`](README.md) | Full plugin documentation, including the relationship to IBTool | +| [`docs/README.md`](README.md) | Full plugin documentation, including the relationship to IB-Tool 3 | | [`docs/CHANGELOG.md`](CHANGELOG.md) | Version history | | [`docs/test-strategy.md`](test-strategy.md) | Test philosophy, tier taxonomy, coverage targets, module-to-test mapping, gap backlog | | [`ai/core/testing-rules.md`](../ai/core/testing-rules.md) | Tactical test rules: geometry checks, QGIS NULL handling, test structure | diff --git a/docs/test-strategy.md b/docs/test-strategy.md index 0025082..89e2ff3 100644 --- a/docs/test-strategy.md +++ b/docs/test-strategy.md @@ -3,7 +3,7 @@ This document is the single authoritative reference for **why** the test suite is structured the way it is, **how** to choose the right test tier for a new test, and **where** known coverage gaps exist. Consult it before writing any new test or assessing CI failures. This plugin follows the same test-strategy structure as its sibling -[IB-Tool-3](https://github.com/IB-Tool/IB-Tool-3/blob/master/docs/test-strategy.md), +[IB-Tool 3](https://github.com/IB-Tool/IB-Tool-3/blob/master/docs/test-strategy.md), scaled down to data_wizard's single-module scope (`processor.py`, `data_wizard.py`, `data_wizard_dialog.py`). @@ -116,7 +116,7 @@ from .layer_factories import ( ### Processing initialization (local runs) -Unlike `QgsApplication.initQgis()`, the `native:*` algorithm provider is **not** auto-registered - it requires the Processing Python plugin's own `Processing.initialize()`. `test/utilities.py`'s `get_qgis_app()` calls this once, immediately after `initQgis()`, so every test file that calls `get_qgis_app()` gets a working `processing.run()` for free. Without this, every `@pytest.mark.integration` test fails with `Algorithm native:... not found`, regardless of whether `QgsApplication` initialized successfully. This is a deliberate deviation from IB-Tool-3's `test/utilities.py`, which does not do this - necessary here because `processor.py`'s pipeline uses `processing.run()` far more heavily than a typical IBTool geometry tool. +Unlike `QgsApplication.initQgis()`, the `native:*` algorithm provider is **not** auto-registered - it requires the Processing Python plugin's own `Processing.initialize()`. `test/utilities.py`'s `get_qgis_app()` calls this once, immediately after `initQgis()`, so every test file that calls `get_qgis_app()` gets a working `processing.run()` for free. Without this, every `@pytest.mark.integration` test fails with `Algorithm native:... not found`, regardless of whether `QgsApplication` initialized successfully. This is a deliberate deviation from IB-Tool 3's `test/utilities.py`, which does not do this - necessary here because `processor.py`'s pipeline uses `processing.run()` far more heavily than a typical IB-Tool 3 geometry tool. ### Fixture scope rules diff --git a/metadata.txt b/metadata.txt index 9918ff6..ab9ef37 100644 --- a/metadata.txt +++ b/metadata.txt @@ -20,7 +20,7 @@ license=GPL-2.0-or-later # Recommended items: hasProcessingProvider=no -changelog=0.1 - Initial release: ATKIS Basis-DLM to HU/RN/Aux GeoPackage conversion for IBTool. +changelog=0.1 - Initial release: ATKIS Basis-DLM to HU/RN/Aux GeoPackage conversion for IB-Tool 3. # Tags are comma separated with spaces allowed tags=python, atkis, data preparation, geodata, vector, ibtool