docs(dev/release): Document crates.io, PyPI, and verification pitfalls

dev/release/README.md

@@ -74,6 +74,14 @@ enable runtime binding generation:
 export SEDONADB_CARGO_TEST_ARGS="--features bindgen"
 ```
 
+The Python test suite includes comparison tests that connect to a PostGIS instance at
+`postgresql://localhost:5432/postgres?user=postgres&password=password` when one is
+reachable. A live PostGIS on localhost is not needed for successful verification;
+however, those who wish to run these extra tests can start the pinned version
+with `docker compose up -d postgis` from the repository root before verifying;
+an unrelated local PostgreSQL listening on port 5432 (e.g., an older PostGIS that
+lacks `ST_HasM`) will cause these tests to fail.
+
 ## Pre-release
 
 Approaching the release date, create a draft pull request into Apache Sedona
@@ -219,8 +227,8 @@ git push upstream apache-sedona-db-0.4.1
 
 The prerelease located at <https://github.com/apache/sedona-db/releases/tag/apache-sedona-db-0.4.1-rc0>
 can now be edited to point to the official release tag and the GitHub release published
-from the UI. The release notes may be automatically generated by selecting
-`apache-sedona-db-0.4.1.dev` as the previous release.
+from the UI. The release notes may be automatically generated by selecting the
+previous release tag (e.g., `apache-sedona-db-0.4.0`) as the previous release.
 
 ### Publish Python package
 
@@ -242,26 +250,59 @@ popd
 ```
 
 Use `twine` to upload the release to PyPI. This will require a token created
-in the PyPI UI.
+in the PyPI UI. The pure-Python packages (e.g., `sedonadb-expr`) are built with
+Metadata-Version 2.5, which requires `twine>=7`. If the token is stored in
+`~/.pypirc`, the `[distutils] index-servers` list must include `pypi` or twine will
+not read the `[pypi]` section. The native wheels are large, so `--skip-existing`
+allows the upload to be resumed if it is interrupted.
 
 ```shell
-# pip install twine
-twine upload wheels/**/*.whl
+# pip install "twine>=7"
+twine upload --repository pypi --skip-existing wheels/**/*.whl wheels/**/*.tar.gz
 rm -rf wheels
 ```
 
 ### Upload to `crates.io`
 
-A script is provided to upload the crates to <https://crates.io>.
+A script is provided to upload the crates to <https://crates.io>. Run it from a
+checkout of the release tag with submodules initialized (the `sedona-s2geography`
+crate compiles the `s2geography` and `s2geometry` submodules during verification).
 
 ```shell
+git checkout apache-sedona-db-0.4.1
+git submodule update --init c/sedona-s2geography/s2geography c/sedona-s2geography/s2geometry
 cargo login
-dev/release/upload-crates-io.sh
+# Validate first, then publish. Tests and the release build can be skipped if the
+# release tarball has already been verified.
+dev/release/publish-crates.sh --dry-run-local
+dev/release/publish-crates.sh --publish --skip-tests --skip-validation
 ```
 
-Currently the `[dev-dependencies]` of some crates need to be modified to avoid circular
-dependencies (we have a PR in the works to remove these circular dependencies), usually
-removing `sedona-testing`.
+If publishing stops partway, fix the problem and resume with
+`--start-from <crate-name>`.
+
+`cargo publish` resolves `[dev-dependencies]` that carry a version requirement, so
+dev-dependencies that form a cycle with a crate published later currently prevent
+publishing. Removing these cycles is tracked in
+[#702](https://github.com/apache/sedona-db/issues/702) (see also
+[#1025](https://github.com/apache/sedona-db/pull/1025)); until that lands, the
+workaround is to remove the offending dev-dependencies from the local checkout used for
+publishing. This is a stopgap: the modifications are never committed, and the published
+crate contents are otherwise identical to the voted release. As of 0.4.1 the cycles are
+`sedona-testing` in `sedona-geometry`, `sedona-gdal`, `sedona-geo-generic-alg`,
+`sedona-raster`, `sedona-expr`, and `sedona-functions`; `sedona-proj` in
+`sedona-functions`; and `sedona` in `sedona-pointcloud`, `sedona-tg`, `sedona-geos`,
+`sedona-geoarrow-c`, and `sedona-s2geography`.
+
+Users with GDAL 3.13+ should also set `GDAL_VERSION=3.12.0` so that the `gdal-sys`
+build script uses its pre-built bindings during the verification builds.
+
+New crates are owned by whoever publishes them first; add the committers team as an
+owner so that future releases can be published by any committer:
+
+```shell
+cargo owner --add github:apache:sedona-committers <crate-name>
+```
 
 ### Publish release blog post