mirror of
https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer.git
synced 2026-10-09 12:27:36 +02:00
david-spacil
d398d2cd1b
Oficiální kontrola pyqgis4-checker (skript pyqt5_to_pyqt6.py z QGISu)
hlásila u pluginu 13 nekompatibilit a tři soubory vůbec nepřečetla.
Odstraněn UTF-8 BOM z amcr_codelists.py, amcr_dialog.py a amcr_tools.py.
Checker čte zdroják jako UTF-8 bez utf-8-sig a na BOM padá na
SyntaxError: invalid non-printable character U+FEFF, takže se ty soubory
nezkontrolovaly vůbec. Pythonu při běhu BOM nevadí, proto to nikdy
nevyskočilo. heslar.csv si BOM ponechává, tam je kvůli Excelu.
Enumy převedeny na plně kvalifikované tvary (13 míst):
Qgis.{Info,Warning,Critical} -> Qgis.MessageLevel.*,
QgsTask.CanCancel -> QgsTask.Flag.CanCancel,
QgsWkbTypes.*Geometry -> QgsWkbTypes.GeometryType.*Geometry.
Zkrácené tvary v QGIS 4.2.1 zatím fungují, ale kontrola je vytýká
a aliasy do budoucna mizí. Zbytek kódu už scoped tvary používal.
Do AGENTS.md doplněna sekce o kompatibilitě s Qt6 / QGIS 4 se závaznými
pravidly a příkazy na ověření.
Ověřeno spuštěním v QGIS 3.44.13 (Qt 5.15.18) i QGIS 4.2.1 (Qt 6.10.3):
importy, vytvoření tasku i všechny tři filtrační dialogy fungují shodně.
Log pyqgis4-checkeru je nově prázdný.
181 lines
8.7 KiB
Markdown
181 lines
8.7 KiB
Markdown
# AGENTS.md
|
||
|
||
Pokyny pro AI agenty i lidské přispěvatele pracující v tomto repozitáři.
|
||
Tento soubor je jediný zdroj pravdy; `CLAUDE.md` na něj pouze odkazuje.
|
||
|
||
## O projektu
|
||
|
||
**AMČR Viewer** je plugin do QGIS pro stahování a vizualizaci dat z Digitálního
|
||
archivu Archeologické mapy ČR (AMČR / AIS CR) – akce (*Fieldwork events*),
|
||
lokality (*Sites*) a jejich komponenty. Podporuje anonymní i přihlášený přístup
|
||
přes AMČR účet.
|
||
|
||
Zdroj dat: https://digiarchiv.aiscr.cz/ · Nápověda: https://amcr-help.aiscr.cz/digiarchiv/qgis-viewer.html
|
||
|
||
## Zařazení v ekosystému AIS CR
|
||
|
||
Tento repozitář je jedním ze **sourozeneckých repozitářů** ekosystému AIS CR.
|
||
Centrální governance a AI konfigurace spravuje hub **`aiscr-management`**; konvence
|
||
v tomto souboru jsou s tímto vzorem sladěné a zjednodušené pro potřeby jednoho
|
||
QGIS pluginu. Těžkou mašinerii hubu (složka `.agents/`, OpenSpec, sync skripty,
|
||
multi-assistant generování) tento repozitář **záměrně nepřebírá**. Při širších
|
||
otázkách governance má přednost vzor z `aiscr-management`.
|
||
|
||
## Struktura repozitáře
|
||
|
||
```
|
||
amcr_viewer/ # vlastní kód pluginu (toto se balí do releasu)
|
||
amcr_viewer.py # vstupní bod pluginu, integrace do QGIS
|
||
amcr_dialog.py # dialogy a UI (filtry, přihlášení)
|
||
amcr_tools.py # stahování dat z API, sestavení vrstev a atributů
|
||
amcr_codelists.py # hesláře / číselníky (codelists)
|
||
codelists/heslar.csv # lokální kopie číselníků
|
||
metadata.txt # metadata pluginu + verze + changelog
|
||
i18n/ # překlady (.ts)
|
||
*.png # ikony
|
||
.github/workflows/ # CI – release pluginu
|
||
README.md # uživatelská dokumentace (anglicky)
|
||
```
|
||
|
||
## Konvence
|
||
|
||
### Jazyk
|
||
- **Kód a identifikátory:** anglicky. Atributová pole vrstev musí být ASCII
|
||
kompatibilní (bez diakritiky) – viz historie změn v `metadata.txt`.
|
||
- **README a uživatelská dokumentace:** anglicky.
|
||
- **Commity, PR a komentáře v issue:** česky.
|
||
|
||
### Commity
|
||
- Styl odpovídá historii: česky, věcně, popisně; jeden commit = jedna logická
|
||
změna.
|
||
- První řádek stručně a výstižně (ideálně v imperativu); podrobnosti do těla.
|
||
- Pokud je commit připraven s pomocí AI, uveď to v těle commitu nebo v popisu PR.
|
||
|
||
### Větve
|
||
Konvence názvů je sladěná s hubem `aiscr-management`:
|
||
|
||
- **lidé:** `feat/<téma>` (nová funkce), `fix/<téma>` (oprava), `docs/<téma>`
|
||
(dokumentace), `chore/<téma>` (údržba).
|
||
- **AI agenti:** `agents/<jméno-agenta>/<téma>` (např. `agents/claude/oprava-pian`).
|
||
|
||
Další pravidla:
|
||
|
||
- Cílová větev pro nový vývoj je aktuální `version/v2.x.y` (ne přímo do
|
||
výchozí větve bez PR).
|
||
- **Nikdy** nepushuj přímo do chráněných větví; vždy přes Pull Request.
|
||
- Standardizační / nefunkční změny drž v samostatné větvi, ať se nemíchají do
|
||
feature PR.
|
||
|
||
### Pravidla pro AI agenty (git)
|
||
- AI ve výchozím stavu zůstává u **lokální práce na aktuální větvi**.
|
||
- Bez **výslovného pokynu** uživatele AI nestageuje (`git add`), necommituje,
|
||
nepushuje ani samo nepřepíná/nezakládá větev pro vzdálené doručení.
|
||
- Při výslovném požadavku na push/PR použij větev `agents/<jméno-agenta>/<téma>`;
|
||
pokud aktuální větev tomuto vzoru neodpovídá, vyžádej si nejdřív potvrzení.
|
||
- Vytvoření větve, stage, commit, push ani draft PR AI běžně nenabízí; zmiňuj je
|
||
jen tehdy, když jsou pro splnění úkolu opravdu nutné.
|
||
|
||
### QGIS specifika
|
||
- Minimální podporovaná verze QGIS je **3.44** (`qgisMinimumVersion` v
|
||
`metadata.txt`); kód nesmí spoléhat na novější API.
|
||
- Vrstvy a atributy se sestavují přes `QgsField` / QGIS API v `amcr_tools.py`.
|
||
Při přidání atributu je potřeba doplnit ho konzistentně na všech místech:
|
||
definice pole (`QgsField`), naplnění hodnoty z dokumentu, překlad hlavičky
|
||
sloupce a export atributů.
|
||
|
||
### Kompatibilita s Qt6 / QGIS 4
|
||
|
||
Plugin cílí na QGIS 3.44 i na QGIS 4 (`qgisMaximumVersion=4.99.0`), tedy na
|
||
Qt5 i Qt6 zároveň. **Tohle se drží rigorózně** – ne až před releasem, ale při
|
||
každé změně kódu. Chování obou větví se liší tiše: pod Qt5 projde i to, co
|
||
QGIS 4 odmítne, takže lokální „funguje mi to“ nic nedokazuje.
|
||
|
||
Závazná pravidla:
|
||
|
||
- **Nikdy neimportuj přímo z `PyQt5` ani z `PyQt6`.** Vždy přes shim
|
||
`qgis.PyQt.*`. Ten mimo jiné pod Qt6 přetahuje `QAction`, `QActionGroup`
|
||
a `QShortcut` z `QtGui`, takže import z `qgis.PyQt.QtWidgets` je správně.
|
||
- **Enumy vždy plně kvalifikované (scoped).** `Qgis.MessageLevel.Info`, ne
|
||
`Qgis.Info`; `QgsTask.Flag.CanCancel`, ne `QgsTask.CanCancel`;
|
||
`QgsWkbTypes.GeometryType.PointGeometry`, ne `QgsWkbTypes.PointGeometry`.
|
||
Totéž pro Qt: `Qt.CheckState.Checked`, `QDialogButtonBox.StandardButton.Ok`.
|
||
Zkrácené tvary sice v QGIS 4.2 zatím fungují, ale oficiální kontrola je
|
||
hlásí a do budoucna mizí.
|
||
- **Zdrojové `.py` soubory ukládej bez BOM.** Kontrolní skript čte soubor
|
||
jako UTF-8 bez `utf-8-sig` a na BOM spadne s
|
||
`SyntaxError: invalid non-printable character U+FEFF`, takže se takový
|
||
soubor **vůbec nezkontroluje**. (`codelists/heslar.csv` BOM mít smí, tam je
|
||
kvůli Excelu.)
|
||
- Nepoužívej API zrušená v Qt6: `exec_()`, `QRegExp`, `QDesktopWidget`,
|
||
`QApplication.desktop()`, `Qt.MidButton`, `QFontMetrics.width()`,
|
||
`setResizeMode`, atributy `AA_EnableHighDpiScaling` / `AA_UseHighDpiPixmaps`.
|
||
- `supportsQt6=True` v `metadata.txt` **nepatří** – bylo zrušeno; o zařazení
|
||
mezi „QGIS 4 Ready“ rozhoduje rozsah `qgisMinimumVersion` až
|
||
`qgisMaximumVersion`.
|
||
|
||
Ověření před PR, který mění Python kód:
|
||
|
||
```sh
|
||
# oficiální kontrola, kterou pouští i plugins.qgis.org (pyqgis4-checker)
|
||
docker run --rm --pull always --user $(id -u):$(id -g) \
|
||
--workdir /workspace/ -v "$(pwd):/workspace/" \
|
||
ghcr.io/qgis/pyqgis4-checker:main-ubuntu \
|
||
pyqt5_to_pyqt6.py --dry_run --logfile /workspace/pyqt6_checker.log .
|
||
```
|
||
|
||
Prázdný log = čisté. Kontrola je na plugins.qgis.org informativní
|
||
(neblokuje schválení), ale nález znamená, že plugin v QGIS 4 dříve nebo
|
||
později přestane fungovat.
|
||
|
||
Když je po ruce QGIS 4 (např. flatpak `org.qgis.qgis`), ověř navíc, že se
|
||
plugin pod Qt6 opravdu načte:
|
||
|
||
```sh
|
||
flatpak run --command=sh org.qgis.qgis -c \
|
||
'PYTHONPATH=/app/share/qgis/python python3 -c "import qgis.core"'
|
||
```
|
||
|
||
## Verzování a release
|
||
|
||
- Verze pluginu žije v **`amcr_viewer/metadata.txt`** (`version=`).
|
||
- **Při každé změně chování / nové funkci** povyš verzi a doplň položku do
|
||
`changelog=` v `metadata.txt` (formát `vX.Y.Z (RRRR-MM-DD)` + odrážky).
|
||
- Datum v changelogu ber z **deterministického zdroje**, ne z paměti, např.
|
||
`python -c "import datetime; print(datetime.date.today().isoformat())"`.
|
||
- Release se spouští **pushnutím tagu `vX.Y.Z`**, ne publikací releasu
|
||
v UI. Workflow `.github/workflows/release_plugin.yml` zabalí složku
|
||
`amcr_viewer/` do `amcr_viewer.zip` a založí **koncept** releasu i s touto
|
||
přílohou; text se dopíše a release zveřejní ručně. Do ZIPu se nesmí dostat
|
||
`.git*` soubory.
|
||
- Organizace má zapnuté **immutable releases** – k publikovanému releasu už
|
||
nelze nic přiložit. Proto příloha vzniká na konceptu, ještě před
|
||
zveřejněním; workflow spouštěný na `release: published` by vždy selhal.
|
||
- Workflow se čte z commitu, na který **tag ukazuje**. Tag proto zakládej až
|
||
na commitu, který obsahuje aktuální podobu workflow – jinak se nespustí nic.
|
||
|
||
## Pull requesty
|
||
|
||
- Používej PR šablonu (`.github/pull_request_template.md`): Souhrn / Změny /
|
||
Testování / Kontrolní seznam.
|
||
- PR musí mířit do správné `version/v2.x.y` větve.
|
||
- Před požádáním o review projdi kontrolní seznam v šabloně (zejména bump verze
|
||
v `metadata.txt`, pokud měníš chování).
|
||
- V popisu PR uveď **podíl AI** (např. „text navržen AI, ručně zkontrolováno")
|
||
a odkaz na související issue, pokud existuje.
|
||
|
||
## Bezpečnost a soukromí
|
||
|
||
- Do promptů, příkladů ani commitů **nevkládej** ostrá produkční data, plné
|
||
log dumpy ani reálné osobní údaje (PII).
|
||
- **Rediguj** secrets, tokeny, API klíče a hesla z čehokoli, co posíláš AI;
|
||
nikdy je necommituj do repozitáře (ani přihlašovací údaje k AMČR účtu).
|
||
- Pro interní infrastrukturu (URL, hostname, prostředí) používej placeholdery,
|
||
pokud konkrétní hodnota není nutná a povolená.
|
||
|
||
## Lokální ověření
|
||
|
||
Plugin se testuje načtením do QGIS (Plugins → Manage and Install Plugins →
|
||
Install from ZIP, nebo nasazením složky `amcr_viewer/` do adresáře pluginů
|
||
QGIS). Automatizované testy zatím repozitář neobsahuje – změny ověřuj ručně
|
||
v QGIS na podporované verzi.
|