pypi publication complicatoins

docs/package-release.md

@@ -0,0 +1,51 @@
+# Python Package Release
+
+`issue-core` publishes as the `issue-core` Python package. The Railiance
+application deployment path expects the `0.2.x` series to be available from the
+Coulomb Gitea PyPI registry.
+
+## Local Release
+
+Build and validate the release artifacts:
+
+```bash
+make package-check
+```
+
+Publish to the Coulomb organization registry:
+
+```bash
+TWINE_USERNAME=<gitea-user> \
+TWINE_PASSWORD=<package-token> \
+make publish-gitea
+```
+
+The package endpoint is:
+
+```text
+https://gitea.coulomb.social/api/packages/coulomb/pypi
+```
+
+The matching simple index for consumers is:
+
+```text
+https://gitea.coulomb.social/api/packages/coulomb/pypi/simple/
+```
+
+Do not commit tokenized package index URLs. CI and local Docker builds should
+inject registry credentials through environment variables or BuildKit secrets.
+
+## Gitea Actions Release
+
+The `.gitea/workflows/publish-python-package.yml` workflow publishes on tags
+matching `v*`. Configure these repository secrets before cutting a release:
+
+- `GITEA_PACKAGE_USER`
+- `GITEA_PACKAGE_TOKEN`
+
+Release `0.2.0` with:
+
+```bash
+git tag v0.2.0
+git push origin v0.2.0
+```