[ixuz]

What and why

The deck of new and changed occupation names promises one version per version of Arbetsförmedlingen's labor market taxonomy. Nothing in this repository noticed a new taxonomy version, though, and the deck's generator stayed behind in antwika/solid-memo, where it wrote the old layout. This brings both here, adapted to how decks are published now.

• Generator (scripts/taxonomy_deck.py): the old script, with its card rules unchanged, ported to decks/<name>/vN.ttl.

  • It reads the deck's newest version and writes the next one beside it. Published versions are never edited, cards are never removed (a card no rule makes any longer is retired), and card ids and dcterms:created dates stay the same.
  • It carries over what it can't make itself: the title, description and keywords in every app language, the creator's name (never an email), and the review activities.
  • It adds the version metadata, the library's contact and the distribution.
  • --check says whether the taxonomy has a newer version. --verify makes the newest version's cards again from the taxonomy and fails unless they come out byte for byte the same. Against the live API it reproduces all 3010 cards of v2.

• Workflow (.github/workflows/taxonomy.yml): runs every Monday, and by hand. When the deck lacks the taxonomy's newest version, it:

  • runs --verify, makes the next version, updates decks/index.ttl, and runs the library check and the pySHACL cross-check;
  • only then makes a token of the GitHub App solid-memo-labour-market-deck, opens the issue "Taxonomy version N is out", and opens a pull request that closes it, or updates the one already open;
  • leaves alone a pull request already open for the same taxonomy version;
  • on a failure, opens an issue or comments on the one already open.

  The App's token is what makes CI run on that pull request: one opened with the workflow's own token starts no workflow. The App's key is a secret of the labour-market-deck environment, which allows only main.

• Docs: docs/deck-library.md covers the deck, the script and the workflow, and how to set up the App. docs/testing.md, the glossary and GOVERNANCE.md mention the new tests, environment and workflow.

The deck stays at deck format 5 and card format 4, as http-status-codes v3 did. Taxonomy version 31, which v2 covers, is still the newest, so the first real run will be for version 32. I tested that path on a simulated v3 (v2 rebuilt at taxonomy version 30, then version 31 added). The library check, the cross-check and the release round-trip tests all accepted it.

Setup outside the code is done, as the taxonomy app describes:

• the App solid-memo-labour-market-deck, with Contents, Issues and Pull requests set to read and write, installed on this repository only;
• the labour-market-deck environment, allowing main only;
• its variable LABOUR_MARKET_DECK_CLIENT_ID and its secret LABOUR_MARKET_DECK_PRIVATE_KEY.

The App is first used when taxonomy version 32 comes out. A run before that skips the update job.

Closes: #189

Checklist

• One issue. This pull request addresses one issue, linked above.
• One step. This pull request does not finish its issue, so it says Refs:, not Closes:. Leave this unchecked otherwise.
• Done, as AGENTS.md defines it: npm run check passes (lint, Markdown and spelling included), npm run lint:reuse too if a file was added, and npm run crosscheck too if ns/ or decks/ changed. (npm run check and npm run lint:reuse pass, and so do npm run lint:workflows and the Python tests; n/a for npm run crosscheck: ns/ and decks/ are unchanged.)
• Tests. New and changed code has its tests, and every package stays at 100% coverage (docs/testing.md). (scripts/test_taxonomy_deck.py: 29 offline tests, run by CI's crosscheck job; no package changed.)
• Docs. The docs say what changed, and a new page in docs/ is listed in docs/docs.ttl. (no new page)
• Languages. A new or changed message is in every locale: en, sv, ko, de, es and fr (packages/ui/src/i18n/). (n/a: no message changed)
• Vocabulary and shapes. Any change to ns/ was agreed in an issue first; no published ns/shapes/*/vN.ttl or decks/*/vN.ttl was edited; generated files were regenerated, not edited.
• Breaking? Nothing in the public API breaks, or a commit says so (! and a BREAKING CHANGE: footer). npm run check:breaking sees a line of api/ that goes, but not a feature removed, nor a reader that reads less than before.
• Pod data. Any change to what the app writes to a pod comes with its migration (docs/migrations.md). (n/a: the app is unchanged)
• Policy. Any change to an external rule the code follows (SM-2, the plural rules, a specification) is cited. (n/a: the deck's rules are the old generator's, documented in its docstring)
• Licenses. New content is MIT, or a deck states its own license; a new file has its SPDX header (npm run lint:reuse), or a new deck its line in REUSE.toml; third-party content is credited. (the taxonomy is CC0 1.0, as the deck already states)
• Architecture. Imports follow docs/boundaries.md and the layers of docs/architecture.md. (n/a: no TypeScript changed)
• Run. I ran the app (npm run dev) and tried the change, and considered the user journeys. (n/a: the app is unchanged; the generator was run against the live taxonomy API)
• Authorship. I read and understand every line of this pull request, and answer for it, whatever tools helped write it (CONTRIBUTING.md).
• Commits. Each commit is one logical change, in Conventional Commits form (type(scope): subject, ! and a BREAKING CHANGE: footer if it breaks something), with an imperative subject and a body that explains why (CONTRIBUTING.md).