PostGIS 3.7.0rc2 released

[Regina Obe]

> docs build still fails with a non-built complaint, without any errors
> reported from doing the docs build.   It's therefore hard to debug.
> It also doesn't make sense why a directory "regress" would be involved in
> building docs.
> 
>   gmake[1]: Entering directory '/tmp/work/databases/postgresql-
> postgis2.update/work/postgis-3.7.0rc2'
>   /usr/pkg/bin/perl ./utils/repo_revision.pl
>   fatal: not a git repository (or any parent up to mount point /)
>   Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not
> set).
>   Can't determine revision from git log
>   Not updating existing rev file at e2ea03a
>   /tmp/work/databases/postgresql-postgis2.update/work/.tools/bin/gmake -C
> doc html
>   gmake[2]: Entering directory '/tmp/work/databases/postgresql-
> postgis2.update/work/postgis-3.7.0rc2/doc'
>   Makefile:626: *** Visual examples are missing. Run 'make -C regress
visual-
> examples' first..  Stop.
>   gmake[2]: Leaving directory '/tmp/work/databases/postgresql-
> postgis2.update/work/postgis-3.7.0rc2/doc'
>   gmake[1]: *** [GNUmakefile:251: docs] Error 2
>   gmake[1]: Leaving directory '/tmp/work/databases/postgresql-
> postgis2.update/work/postgis-3.7.0rc2'
>   gmake: *** [Makefile:7: docs] Error 2
>   *** Error code 2
> 

The compile error is just bogus.  Stems from the fact that visual-examples
aren't built.
On my system I get this now from building from the tarball and running
commands:

make -C doc html

wrote /projects/postgis/postgis-3.7.0rc2/doc/html/postgis-ref-index.json and
/projects/postgis/postgis-3.7.0rc2/doc/html/postgis-ref-index.js;
commands=1, functions=630, operator pages=37, SQL keywords=63
Makefile:626: *** Visual examples are missing. Run 'make -C regress
visual-examples' first..  Stop.
make: Leaving directory '/projects/postgis/postgis-3.7.0rc2/doc'

Which I felt was much clearer than it recursing on each step and failing
cause it couldn't find the images.

Not sure why yours continues to recurse on.  Before I made the change to the
steps to just exit, I was getting the same results you were.

> Reading NEWS:
> 
>   To build docs, first run visual examples and make sure you have a
running
>   PostgreSQL instance.
> 
>   `make -C regress visual-examples`
> 
> this is really problematic and outside the normal boundaries.
> 
>   - "run visual examples" does not parse
>   - "make sure you have a running postgresql instance" is not ok.  When
>      building packages, they're in a sandbox and while package building
>      machines do run build tools, but requiring someone to start up a
>      database is way too much for this kind of environment
>   - "build docs" and "regress" do not belong together
> 

You need a running PostgreSQL to regress test don't you?  I fail to see the
issue here.
But yes our image examples are doing double duty of testing the
documentation and building the images.
pgRouting also follows this -- though their doc queries just output results
not the images and those results are included in the docs.
https://github.com/pgRouting/pgrouting/tree/develop/docqueries

> 
> I see in README.postgis description of doc requirements and will
> crosscheck that.   I think there's a makefile bug where missing prereqs
> lead to steps being skipped, instead of erroring.
> 
> 
> Perhaps pgsql is run within the build temporarily, like regression tests
do.
> That's still not great for docs, but it's less problematic than expecting
db setup
> 
> 
> I'll look into this before, but I wanted to test/write quickly that rc2 is
not
> suitable for release.  I hope these issues are relatively easy to address.

Yah I was debating that but I feared trying to change that would just break
things in more vulnerable ways.
Do you agree the best course of action is just to advice people to NOT try
to build docs unless they are contributing to the project
and just make it very clear where they can download them pre-built?

Even if contributing I'd probably say it's not necessary as I document a lot
and never have had a need to build the docs myself. Always relied on the CI
to do that.