Skip to content

Fix/opensak parser v1.22.0 - #22

Open
nagisml wants to merge 3 commits into
OpenSAK-Org:mainfrom
nagisml:fix/opensak-parser-v1.22.0
Open

nagisml wants to merge 3 commits into
OpenSAK-Org:mainfrom
nagisml:fix/opensak-parser-v1.22.0

Conversation

@nagisml

@nagisml nagisml commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Load OpenSAK's parser with deprecation.py; bump opensak-ref to v1.22.0

From v1.22.0, OpenSAK's src/opensak/macro/metadata.py imports
opensak.macro.deprecation, so downloading metadata.py alone fails with
ModuleNotFoundError. OpenSAK keeps deprecation.py free of other OpenSAK
imports so the two files work together outside OpenSAK.

  • check.yml and index.yml download metadata.py and deprecation.py
    (PARSER_FILES) into an opensak/macro/ folder.
  • load_metadata_module() in check_macro_pr.py and build_index.py puts
    the folder above opensak/macro/ on sys.path. The scripts run under
    python -I, which ignores PYTHONPATH. A parser in any other place (e.g.
    beta.9 on its own) is loaded as before.
  • The tests expect the parser at .tools/opensak/macro/metadata.py;
    their docstring explains how to download both files.
  • .github/opensak-ref: v1.22.0-beta.9 -> v1.22.0 (2f05c47).
  • MAINTAINERS.md explains the two-file setup and what to do if a later
    bump fails with ModuleNotFoundError.
  • v1.22.0 blocks more Geocaching HQ domains (Groundspeak, Waymarking,
    Wherigo, ...): CONTRIBUTING.md and the GitHub website guide now say so.
  • "headless" in index.json stays null: v1.22.0 has no Headless header
    key yet (planned in OpenSAK #1195). The comment and MAINTAINERS.md
    wrongly tied it to API 4.

Add scripts/build_index.py and the Index workflow. After every push to
main, the workflow builds index.json from main's git history and
publishes it on the "index" branch:

  https://raw.githubusercontent.com/OpenSAK-Org/OpenSAK-Macros/index/index.json

OpenSAK's Macro manager can read this file to list, install and update
macros without walking the repository through the GitHub API.

Per macro the index holds:
- the header, read with OpenSAK's own parser (from .github/opensak-ref)
- every file in its folder, with size, SHA-256 and a download URL
  pinned to the commit
- every version that was on main: publish date, SHA-256, size,
  Requires-API and permissions of the macro file
- the changelog from the "## Changes" list in its README

Macros removed from main are listed under "withdrawn" with the hashes
of all their versions, so an installed copy can be recognised.

The script only reads git objects and never runs macro code. The same
commit always gives the same file, and a run that changes nothing
pushes nothing. MAINTAINERS.md describes the format (schema 1).
CONTRIBUTING.md and the template README now ask for a "## Changes"
line per version.
From v1.22.0, OpenSAK's src/opensak/macro/metadata.py imports
opensak.macro.deprecation, so downloading metadata.py alone fails with
ModuleNotFoundError. OpenSAK keeps deprecation.py free of other OpenSAK
imports so the two files work together outside OpenSAK.

- check.yml and index.yml download metadata.py and deprecation.py
  (PARSER_FILES) into an opensak/macro/ folder.
- load_metadata_module() in check_macro_pr.py and build_index.py puts
  the folder above opensak/macro/ on sys.path. The scripts run under
  python -I, which ignores PYTHONPATH. A parser in any other place (e.g.
  beta.9 on its own) is loaded as before.
- The tests expect the parser at .tools/opensak/macro/metadata.py;
  their docstring explains how to download both files.
- .github/opensak-ref: v1.22.0-beta.9 -> v1.22.0 (2f05c47).
- MAINTAINERS.md explains the two-file setup and what to do if a later
  bump fails with ModuleNotFoundError.
- v1.22.0 blocks more Geocaching HQ domains (Groundspeak, Waymarking,
  Wherigo, ...): CONTRIBUTING.md and the GitHub website guide now say so.
- "headless" in index.json stays null: v1.22.0 has no Headless header
  key yet (planned in OpenSAK #1195). The comment and MAINTAINERS.md
  wrongly tied it to API 4.
@github-actions github-actions Bot added the needs review Waits for a maintainer label Nov 18, 2026
"Check macro" reads .github/opensak-ref from main, so a pull request
that adds deprecation.py to the download list was checked against
main's beta.9 ref, where that file doesn't exist (404).

metadata.py stays a required download. The modules it imports
(PARSER_DEPS: deprecation.py) are downloaded if the ref has them; an
older ref doesn't need them, and if a needed one is missing, loading
the parser still fails with ModuleNotFoundError.

auto-merge.yml downloaded metadata.py on its own. With v1.22.0 the
check there would fail and, because of "|| true", quietly make every
pull request ineligible for auto-merge. It now uses the same
opensak/macro/ layout and downloads deprecation.py too.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs review Waits for a maintainer

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant