Release readiness (publish-last): investigate this repo's FIRST release — no tags exist; LFS assets; coding-decision stance

[Polichinel]

Release runbook: views-postprocessing FIRST release (publish-last; executes ONLY on Simon's platform signal)

Investigated and rewritten 2026-07-28 per this issue's original mandate (original text preserved at bottom). Every fact below verified in-repo or against live PyPI/remotes on that date.

1. What "release" means here — three things at once

This repo is both a package and a deployed-style service: it ships as the poetry package views-postprocessing (name free on PyPI — never published), and it runs in production as an editable checkout imported by views-models' postprocessors/un_fao/main.py (verified: the runtime env's install is Editable project location: …/views-postprocessing). The first release is therefore:

1. Git: merge development→main, tag, GitHub release (notes below).
2. PyPI: publish via the existing publish_package.yml (triggers on GitHub release; token secret must exist — verify before the signal).
3. Operations unchanged: the production consumer stays on the editable checkout; PyPI existence is for reproducibility/pinning, not a deployment change.

2. Distance & divergence — clean straight merge, with one deliberate deletion riding it

development is 197 ahead / 0 behind main (grew from the issue's 187). Zero divergence → straight merge. Notable: the merge DELETES the LFS-tracked GAUL_2024 shapefiles + .gitattributes that only main still carries (development replaced them with the 888 KB precomputed ADR-011 lookup in June). After release, no LFS assets exist at HEAD — the "LFS precedent" cited from views-reporting C-23 describes pre-merge main and should be corrected there (history still holds the blobs; clone size note only). Fresh installers get a plain 888 KB parquet.

3. Version proposal: 1.0.0

Never tagged; pyproject says 0.1.0. Proposal: 1.0.0 — this repo owns an adopted, falsification-audited cross-repo contract (ADR-013), and its delivery machine shipped the first real production run (run-0, 2026-07-27, verified in the live store). Matches views-faoapi's v1.0.0-at-production-readiness convention. Breaking-change note for the release: none for external consumers (there were no prior releases); for the one operational consumer (views-models), the wire_contract/wire_upload_enabled launch keys are additive.

4. Dependency pins & release order — the coordination core

Current pins (pyproject): views-pipeline-core >=2.1.3,<3.0.0 · views-frames >=1.0,<2 · pyarrow >=16.1.0,<17 (first-class pin since the fixture re-baseline).

The trap this investigation caught: pipeline-core's PyPI latest is 2.3.0, which satisfies our written pin — but our runtime floor is HIGHER than anything released: we consume get_feature_frame / declared_data_format (#126) and interoperate with sampled_forecast_publisher (#269/#276), all unreleased. A PyPI-only install under today's pin would import-error at runtime. Action at signal: bump the pipeline-core pin to >=<their next release> before tagging.

Order: views-frames (released ✓) → views-pipeline-core (their next release) → views-postprocessing → (views-models, if it releases — it consumes us). views-reporting is order-independent of us (no dependency either way; verified pyproject).

Undeclared soft dependency, declared here for honesty: datafactory_query is imported lazily by source_metadata.py with degrade-open semantics — deliberately NOT a pyproject dep (works without it; clip skipped with a warning). Release notes should state this.

5. Splash zone

• views-models — the only importer (postprocessors/un_fao/main.py; the reconciliation import was retired to views-frames in June). Editable checkout; nothing breaks; they may pin the PyPI version afterwards.
• views-faoapi — consumes our artifacts (bucket), never our package. No impact.
• Org code search: no other views_postprocessing importers.

6. Repo-specific gates (all verifiable before the signal)

• CI green on the merge (pytest is the CI gate; the 5 toolchain byte-parity tests pass in CI's poetry env by design; test_datafactory_deploy_readiness is machine-local-skipped — C-46).
• publish_package.yml secret PYPI_TOKEN exists (org/repo secret — VERIFY, we cannot see it).
• Governance: add the release as a dated ADR-013 post-adoption entry; register housekeeping (C-46 re-pin decision at release is a good moment).
• Release-notes source: full git log (no prior tag). Suggested arc: input-integrity sprint (Epic: FAO delivery input-integrity — complete-coverage contract + no silent bad data #51) → reconciliation retirement (C2 — Retire views_postprocessing/reconciliation/ (moved to views_frames_reconcile) #62) → ADR-013 wire contract + Hop-B delivery epic ([EPIC] ADR-013 Hop-B sink leg: frame-native FAO delivery (shards + sidecar + run manifest + gates) #105) → frame-native + streaming OOM fixes (un_fao: retire the pandas historical path — deliver frame-native end-to-end (fixes run-0 OOM) #126) → run-0 delivered (run-0 DELIVERED: first FAO global-land forecast shipped frame-native (OOM gone) — verify delivery integrity? #131).

7. Cross-repo stances & checks

• Country-coding (Decision needed: GAUL country coding — Kosovo/disputed territories + who owns the GAUL↔VIEWS crosswalk #123 / views-datafactory#341): this repo's released stance = the ADR-011 GAUL-derived lookup (FAO's own atlas; 202 clean iso3 codes verified; the 76 GAUL-uncovered cells excluded by declared rule). The M49 add is scoped and deliberately deferred (falsified as a quick add: the Taiwan coding decision + a 4-stop declared chain — see the 2026-07-25 falsification). Release does NOT wait, mirroring views-reporting's declared-interim approach.
• views-reporting#179: their C-23 LFS note cites our pre-merge main; after our merge it's stale — comment to be posted at signal time.
• Siblings get one-line cross-links at signal time (pipeline-core, views-models prep issues).

Execution checklist (NOTHING runs before Simon's signal)

• Confirm pipeline-core's release version; bump our pin; commit on development
• Verify PYPI_TOKEN secret exists
• Merge development→main (straight; LFS deletion rides along); CI green on main
• Bump pyproject to the agreed version (proposal: 1.0.0); tag v1.0.0; GitHub release with the notes arc above
• Confirm publish_package.yml published to PyPI; pip install views-postprocessing smoke-imports
• ADR-013 post-adoption entry + register notes; correct views-reporting C-23; cross-link siblings

---

Original issue text (preserved per mandate)

Why this issue exists (cross-repo context — read first)

The VIEWS platform develops on development branches under a publish-last rule: no tags, version bumps, or releases in any platform repo until Simon gives the platform-wide publish signal, and then all repos release together (views-frames is the already-released exception). That signal is coming; each repo needs its own release runbook ready BEFORE it fires.

What views-reporting will do (its release issue, views-platform/views-reporting#179, is already a full runbook): on the signal — merge development→main (149 commits), bump 0.2.0→0.3.0, tag, GitHub release, publish to PyPI. Notable contents: the breaking EvaluationReportTemplate.generate(source=, target=) inversion (MetricFrame EvaluationSource, their #173); the global-PGM map product (ADR-021: global metadata bundle via a declared-interim GAUL→ISO3→VIEWS crosswalk — register C-211 there; horizon-step maps; MAP/P(any)/HDI layers); S=1000 memory feasibility; ~37 MB offline reports. The interim crosswalk is declared, not hidden — their release does NOT wait for the platform country-coding decision (views-datafactory#341 / views-postprocessing#123).

This issue is deliberately NOT a finished runbook. It records what is knowable from outside this repo (below) and asks the agent/maintainer working IN this repo to investigate and then rewrite this issue into the repo's own release runbook — the way views-reporting#179 was rewritten.

What is knowable from outside this repo (verify all of it)

• NOT on PyPI and no tags exist at all — this repo has never released. Decide what its first release IS (PyPI package? tag-only? none — maybe it's deploy-style?) and what version to start at.
• development is 187 ahead / 0 behind main — a clean straight-merge candidate, pending your investigation.
• Known cross-repo threads touching you: you carry the PRIO-GRID shapefile via git-lfs (views-reporting's register C-23 cites you as the LFS precedent — a release should confirm LFS assets resolve for installers/cloners); and you co-own the open platform country-coding decision (your Decision needed: GAUL country coding — Kosovo/disputed territories + who owns the GAUL↔VIEWS crosswalk #123 / views-datafactory#341 — Kosovo/GAUL). That decision does NOT block anyone's release (views-reporting ships the declared interim), but your release notes should state your repo's current stance/state on it.
• Investigate your dependency pins on views-pipeline-core / views-reporting / views-frames and place yourself in the release order accordingly.

Your task: investigate, then turn THIS issue into this repo's release runbook

Answer at least the following, in this issue (rewrite the body; preserve this original text at the bottom):

1. What does "release" even mean here? PyPI package, GitHub release/tag only, a pinned environment, a deployed artifact — or several of these?
2. Distance + divergence: what exactly is in development that main lacks (and vice versa — see the facts below); is main releasable after a straight merge, or is there drift to reconcile first?
3. Version proposal + breaking changes: last released/tagged version vs today's content; what breaks for consumers; what semver/0.x convention applies here.
4. Dependency pins & ordering (the coordination core): which platform packages does this repo depend on (views-pipeline-core, views-reporting, views-frames, datafactory, …), at what pins today (dev-installs? git refs? released versions?), what must those pins become at release, and therefore WHERE in the platform release order this repo sits (who must publish before you; who waits for you).
5. Splash zone / consumers: who consumes THIS repo's released artifact (other platform repos, CI pipelines, partner installs, model runs) and what breaks for them; run an org code search if unsure.
6. Repo-specific gates: CI green on main after the merge; any data/asset questions (large files, LFS, bundled data); any register/ADR/CIC updates your governance requires around a release; release-notes source (git log <last-tag>..main).
7. Cross-repo checks: read Release views-reporting with the MetricFrame EvaluationSource (#173) — publish-last for pipeline-core #224 views-reporting#179 for the template and the ordering constraints already known; comment there (and on the sibling issues listed below) if your investigation contradicts anything.

Hard rule: nothing executes until Simon's platform-wide publish signal. Investigating and rewriting this issue is in scope now; merging/tagging/publishing is not.

Siblings: views-platform/views-reporting#179 (the template), views-pipeline-core and views-models carry the same prep issue (cross-linked in comments).

[Polichinel]

Siblings: views-platform/views-pipeline-core#313, views-platform/views-models#282; template: views-platform/views-reporting#179.

[Polichinel]

Data point from the pipeline-core release investigation (views-platform/views-pipeline-core#313): your pyproject pins views-pipeline-core = ">=2.1.3,<3.0.0" — the platform release publishes pipeline-core 3.0.0 (large breaking jump: ADR-054 extraction complete, PredictionFrame is the views-frames leaf, shims retired). Your runbook needs an explicit bump-or-stay decision: PyPI 2.3.0 keeps serving your current cap unchanged, so staying is safe short-term; bumping means absorbing the 3.0.0 breaking set.