Document release publishing follow-up

Author: bhack

docs/flathub.md

@@ -56,7 +56,8 @@ release, then update the Flathub manifest to the new release archive.
 
 1. Finish the upstream release and confirm the GitHub release is not a draft.
 2. Confirm the release is suitable for Flathub stable, not a nightly snapshot.
-3. Build or download the release source archive and compute its SHA-256.
+3. Download the published release source archive and compute or confirm its
+   SHA-256.
 4. In the Flathub repository, update the `mini-eq` module source to the new
    release URL and hash.
 5. If the screenshot changed, update the MetaInfo screenshot URL to a release
@@ -80,6 +81,27 @@ release, then update the Flathub manifest to the new release archive.
 15. If quality fixes landed, use the listing quality panel to request a
     re-review.
 
+GitHub draft releases expose assets under temporary `untagged-*` URLs. Publish
+the upstream GitHub release first, then use the stable asset URL:
+
+```bash
+curl -fsSL \
+  https://github.com/bhack/mini-eq/releases/download/vX.Y.Z/mini_eq-X.Y.Z.tar.gz \
+  | sha256sum
+```
+
+The Flathub `master` branch is protected, so direct pushes are rejected. Push an
+update branch and open a PR:
+
+```bash
+git switch -c update-X.Y.Z
+git push -u origin update-X.Y.Z
+gh pr create --repo flathub/io.github.bhack.mini-eq \
+  --base master \
+  --head update-X.Y.Z \
+  --title 'Update mini-eq to X.Y.Z'
+```
+
 ## Validation
 
 Run upstream AppStream and desktop-file validation:
@@ -104,6 +126,21 @@ flatpak run --command=flathub-build org.flatpak.Builder --install io.github.bhac
 flatpak run io.github.bhack.mini-eq --check-deps
 ```
 
+For a local source and full build check without installing the app:
+
+```bash
+flatpak run --command=flatpak-builder org.flatpak.Builder \
+  --force-clean \
+  --download-only \
+  --install-deps-from=flathub \
+  build-dir io.github.bhack.mini-eq.yaml
+flatpak run --command=flatpak-builder org.flatpak.Builder \
+  --force-clean \
+  --install-deps-from=flathub \
+  --repo=repo \
+  build-dir io.github.bhack.mini-eq.yaml
+```
+
 If a `repo/` is produced, run:
 
 ```bash

docs/release.md

@@ -45,6 +45,39 @@ and attaches the built wheel and sdist. Keep `draft=true` for the first run,
 review the generated notes and assets on GitHub, then publish the draft
 manually.
 
+For a production GitHub release plus PyPI publish, dispatch with:
+
+```bash
+gh workflow run release.yml --repo bhack/mini-eq --ref main \
+  -f dry_run=false \
+  -f create_github_release=true \
+  -f tag_name=vX.Y.Z \
+  -f target=main \
+  -f draft=true \
+  -f prerelease=false \
+  -f publish_testpypi=false \
+  -f publish_pypi=true
+```
+
+If the `pypi` environment requires approval, the publish job will stay in
+`waiting` until the deployment is approved in GitHub Actions. The same approval
+can be done with `gh` when the logged-in account is allowed to approve:
+
+```bash
+run_id=<workflow run id>
+gh api "repos/bhack/mini-eq/actions/runs/${run_id}/pending_deployments"
+environment_id=1234567890
+gh api "repos/bhack/mini-eq/actions/runs/${run_id}/pending_deployments" \
+  -X POST \
+  -F environment_ids[]="$environment_id" \
+  -f state=approved \
+  -f comment='Publish vX.Y.Z to PyPI'
+```
+
+Draft GitHub release assets use temporary `untagged-*` download URLs. Publish
+the draft before using release asset URLs in the Flathub manifest or other
+public metadata.
+
 Set `publish_testpypi=true` only after the `testpypi` GitHub environment and
 TestPyPI trusted publisher are configured. The TestPyPI job uses
 `pypa/gh-action-pypi-publish` with OIDC and does not use API tokens. Keep PyPI
@@ -128,3 +161,14 @@ For production PyPI publishing, dispatch the workflow with `dry_run=false`,
 `create_github_release=true`, `tag_name=vX.Y.Z`, and `publish_pypi=true`.
 Use Trusted Publishing/OIDC and the separate `pypi` environment rather than
 long-lived API tokens.
+
+After the workflow completes:
+
+```bash
+gh release view vX.Y.Z --repo bhack/mini-eq --json tagName,isDraft,isPrerelease,assets,url
+curl -fsSL https://pypi.org/pypi/mini-eq/json | jq -r '.info.version'
+git ls-remote --tags origin vX.Y.Z
+```
+
+Publish the draft GitHub release after reviewing its notes and assets. Then use
+the published release tarball and SHA-256 for the Flathub repository update.