PostGIS 3.7.0rc2 released

[Greg Troxel]

"Regina Obe" <lr at pcorp.us> writes:

>> I think I understand better now.
>> 
>> * details
>> 
>> rsvg-convert is listed as needed, but configure.ac doesn't look for it.
>> It does look for convert, but doesn't check that it does what you need -
> I'm
>> unclear on if a working convert always does, or if it's optional.
>
> Hmm that shouldn't be needed.  My understanding is that it is preferred but
> not required if you have ImageMagick or GraphMagick
> Darafei can you confirm?  I have neither locally.

"convert" is part of ImageMagick.

My point is that if the build is maybe going to use rsvg-convert, it
should probably be checked for by configure and listed in the configure
results.  The only thing that's obvious here is that the docs build
process is too complicated and too hard to understand.


>> * big picture
>> 
>> Within the "make docs" top-level target there are a lot of subsidiary docs
>> targets.  Some of them fall into "things a package ought to have
> installed", and
>> some seem more obscure.  In packaging, what I want is a way to ask for the
>> things that belong in a package.  If visual examples require things that
> aren't
>> compatible  with packaging build environments, I'm ok with having those be
>> off.
>> 
>> Looking in doc/Makefile I see
>> 
>>   ifeq ($(CAN_BUILD_COMMENTS),yes)
>>   BUILD_TARGET += comments
>>   endif
>> 
> The comments build doesn't need visual examples.  Are you having trouble
> building that?

I am getting an error doing "make docs" from top-level.  The build
instructions are unclear about what kinds of docs there are.

> I can revisit that to make sure I didn't screw that up when I made changes
> to the visual examples thing.

There seems to be a clear regression with 3.7.0

> PDF and epub do require visual examples but those should be tested now and
> should be cleanly erroring if you haven't built the visual examples.

I ran 'make docs'.  Perhaps the real issue is this concept of a manual
build step for visual examples.  There should not be any manual build
steps!

> For the most part we haven't been worried too much about docs as long as our
> CI that packages releases can build them.

I don't see that as the right approach.  Everything should work,
everywhere, and the point of CI is to verify that.  Of course CI is
incomplete and things slip through, but that sounds like "if it builds
in our CI, it's not a bug".

> I think most packagers just use our pre-built docs:
> Which for this release - https://postgis.net/stuff/postgis-3.7-en.pdf and
> https://download.osgeo.org/postgis/docs/doc-html-3.7.0rc2.tar.gz
>
> Though I realize now I never bothered to link the html ones, probably cause
> I take it for granted people would just read them online  or use the pdf for
> offline use which 
> are always listed here for our supported versions -
> https://postgis.net/documentation/manual/

I see open-source norms as requiring:
  - documentation should be part of packages so it's available without
    the net
  - built docs are binaries and anyone must be able to build docs from
    the doc sources
  - all of this should be encapsulated in a build procedure that does
    not require manual steps

> Users I suspect don't care about building docs if they are building for
> themselves and frankly our build chain especially now that we have
> translations 
> Is very complicated and has always been complicated (perhaps a bit more so
> with the introduction of our (lets make sure our docs reflect our changes in
> the branch) which is why we have this new fangled visual examples build that
> actually tests our doc examples to generate the images.  I wouldn't want any
> packager to waste time trying to get all the glue to make that work unless
> they have a pressing requirement to do so.
> It's best just downloaded and installed.

That sounds like "this is open source in name only; just use our docker
container"!