pypi publication complicatoins

workplans/ISSUE-WP-0002-gitea-pypi-publication.md

@@ -0,0 +1,83 @@
+---
+id: ISSUE-WP-0002
+type: workplan
+title: "Publish issue-core to Gitea PyPI"
+domain: custodian
+repo: issue-core
+status: blocked
+owner: codex
+topic_slug: custodian
+created: "2026-05-23"
+updated: "2026-05-23"
+state_hub_workstream_id: "87a5dcb6-5b2c-4d3f-8d5c-e265889b0fc6"
+---
+
+# Publish issue-core to Gitea PyPI
+
+`issue-core` needs a first real Python package release in the Coulomb Gitea
+package registry so downstream applications can depend on a versioned package
+instead of a sibling checkout path.
+
+## Publish and verify the Gitea PyPI package
+
+```task
+id: ISSUE-WP-0002-T01
+status: blocked
+priority: high
+state_hub_task_id: "f0df7dbc-b55d-4835-a528-f44a329efb0e"
+```
+
+**Problem.** `vergabe-teilnahme` and future Railiance S5 apps need
+`issue-core` as a normal package dependency. A local dependency such as
+`issue-core @ file:///home/worsch/issue-core` makes Docker builds depend on a
+specific operator workstation and forces non-portable BuildKit named contexts.
+
+**Current state.** The repo has package release plumbing prepared:
+
+- `make package-check` builds and validates `issue-core==0.2.0`.
+- `make publish-gitea` uploads `dist/*` to the Coulomb Gitea PyPI endpoint.
+- `.gitea/workflows/publish-python-package.yml` can publish on `v*` tags once
+  package registry secrets exist.
+- `docs/package-release.md` documents local and tag-based publishing.
+
+**Blocker.** Publishing requires a Gitea package username/token with permission
+to upload to:
+
+```text
+https://gitea.coulomb.social/api/packages/coulomb/pypi
+```
+
+No publish credentials are currently available in the shell or standard package
+config files.
+
+**Implementation steps.**
+
+1. Configure Gitea repository or organization secrets:
+   `GITEA_PACKAGE_USER` and `GITEA_PACKAGE_TOKEN`.
+2. Publish `issue-core==0.2.0` either by pushing tag `v0.2.0` or by running:
+
+   ```bash
+   TWINE_USERNAME=<gitea-user> \
+   TWINE_PASSWORD=<package-token> \
+   make publish-gitea
+   ```
+
+3. Verify the simple index exposes the package:
+
+   ```bash
+   curl -fsS https://gitea.coulomb.social/api/packages/coulomb/pypi/simple/issue-core/
+   ```
+
+4. Verify a clean environment can install the package from the Gitea simple
+   index with credentials injected outside Git.
+5. Coordinate with `vergabe-teilnahme` to regenerate its `uv.lock` from the
+   published package and confirm its Docker build no longer needs the sibling
+   `issue-core` checkout.
+
+**Done when.**
+
+- `issue-core==0.2.0` is visible in the Coulomb Gitea PyPI simple index.
+- A clean Python environment can install `issue-core>=0.2,<0.3` from Gitea.
+- The publish workflow has the required secrets and a documented release path.
+- The Railiance app deployment blocker can be closed without relying on local
+  path dependencies.