readme.md tagged version section is confusing

[nydydn]

What is the bug or the crash?

I believe that the readme is if not wrong, at least confusing:

It is mentioned that:

kartoza/postgis:17-3.5 Provides PostgreSQL 17.0, PostGIS 3.5

but currently this is false, as kartoza/postgis:17-3.5 provides PostgreSQL 17.4, PostGIS 3.5
I believe the intention was to mention that kartoza/postgis:17-3.5 Provides PostgreSQL 17.x, PostGIS 3.5

Further, there is the following note:

Note: We highly recommend that you use tagged versions because successive minor versions of PostgreSQL write their database clusters into different database directories - which will cause your database to appear to be empty if you are using persistent volumes for your database storage.

I don't think that is true. I believe that on successive major versions of PostgreSQL may change database directories and never minor versions. Isn't this the main difference between major and minor versions?

I really am no expert, so please correct me if I am grossly misunderstanding something and somehow the documentation is correct as it is.

Nevertheless, I believe one more paragraph of what an upgrade entails would be welcomed by novices. For example a note that says:

Upgrade between minor versions are done by pulling the latest tagged version, for example kartoza/postgis:17-3.5 might have contained 17.0 when first installed, but after being repulled it may contain 17.4 and the upgrade between minor versions will be done automatically.
Upgrade between major versions require dumping and re-importing data, please follow upgrade requirements on the PostgreSQL documentation.

Steps to reproduce the issue

1. Check README.md
2. Be confused about what version the tag 17-3.5 should provide, which is mentioned to be 17.0
3. Check what gets installed when using tag 17-3.5, and observe it is 17.4, which is different from the documentation
4. Check if database directories were restructured as mentioned in documentation for minor versions
5. Observe that the upgrade was done successfully for minor versions, in spite of what the documentation mentions about upgrades between minor versions

Versions

17-3.5

Additional context

Technically this is not a bug, and it is neither a feature request, so I'm knowingly breaking the rules, but this would not have fitted on the postgres mailing list, or stackexchange either, as it is very much specific to this very github repository, even specific to a few lines of a file whose truth source is this repository. I believe it may alienate possible contributors to not welcome such reports, even if they're merely about documentation.

[NyakudyaA]

What is the bug or the crash?

I believe that the readme is if not wrong, at least confusing:

It is mentioned that:

kartoza/postgis:17-3.5 Provides PostgreSQL 17.0, PostGIS 3.5

but currently this is false, as kartoza/postgis:17-3.5 provides PostgreSQL 17.4, PostGIS 3.5 I believe the intention was to mention that kartoza/postgis:17-3.5 Provides PostgreSQL 17.x, PostGIS 3.5

You are correct here, this need to be updated.

Further, there is the following note:

Note: We highly recommend that you use tagged versions because successive minor versions of PostgreSQL write their database clusters into different database directories - which will cause your database to appear to be empty if you are using persistent volumes for your database storage.

I don't think that is true. I believe that on successive major versions of PostgreSQL may change database directories and never minor versions. Isn't this the main difference between major and minor versions?
You are write again, but the main issue of using tagged version lies in repeatability as latest can have breaking changes while the tagged versions are ussually kept as is unless we are fixing a bug in the code base. Also each merged PR contains https://github.com/kartoza/docker-postgis/releases to allow users to switch to a known working version or to inspect changes

I really am no expert, so please correct me if I am grossly misunderstanding something and somehow the documentation is correct as it is.

Nevertheless, I believe one more paragraph of what an upgrade entails would be welcomed by novices. For example a note that says:

Upgrade between minor versions are done by pulling the latest tagged version, for example kartoza/postgis:17-3.5 might have contained 17.0 when first installed, but after being repulled it may contain 17.4 and the upgrade between minor versions will be done automatically. Upgrade between major versions require dumping and re-importing data, please follow upgrade requirements on the PostgreSQL documentation.

Very, true. An alternative would be to actually tag the images appropriately so that we can infer the versions by the name i.e. kartoza/postgis:17.4-3.5, but the statement should ideally state that "The minor version is currectly pinned to the version available at the time of publishing the image, which i think is not appropriate. I will fix this in an upcoming PR but you are welcome to do a PR with the Readme suggestions"

Steps to reproduce the issue

1. Check README.md

2. Be confused about what version the tag 17-3.5 should provide, which is mentioned to be 17.0

3. Check what gets installed when using tag 17-3.5, and observe it is 17.4, which is different from the documentation

4. Check if database directories were restructured as mentioned in documentation for minor versions

5. Observe that the upgrade was done successfully for minor versions, in spite of what the documentation mentions about upgrades between minor versions

Versions

17-3.5

Additional context

Technically this is not a bug, and it is neither a feature request, so I'm knowingly breaking the rules, but this would not have fitted on the postgres mailing list, or stackexchange either, as it is very much specific to this very github repository, even specific to a few lines of a file whose truth source is this repository. I believe it may alienate possible contributors to not welcome such reports, even if they're merely about documentation.

What is the bug or the crash?

I believe that the readme is if not wrong, at least confusing:

It is mentioned that:

kartoza/postgis:17-3.5 Provides PostgreSQL 17.0, PostGIS 3.5

but currently this is false, as kartoza/postgis:17-3.5 provides PostgreSQL 17.4, PostGIS 3.5 I believe the intention was to mention that kartoza/postgis:17-3.5 Provides PostgreSQL 17.x, PostGIS 3.5

Further, there is the following note:

Note: We highly recommend that you use tagged versions because successive minor versions of PostgreSQL write their database clusters into different database directories - which will cause your database to appear to be empty if you are using persistent volumes for your database storage.

I don't think that is true. I believe that on successive major versions of PostgreSQL may change database directories and never minor versions. Isn't this the main difference between major and minor versions?

I really am no expert, so please correct me if I am grossly misunderstanding something and somehow the documentation is correct as it is.

Nevertheless, I believe one more paragraph of what an upgrade entails would be welcomed by novices. For example a note that says:

Upgrade between minor versions are done by pulling the latest tagged version, for example kartoza/postgis:17-3.5 might have contained 17.0 when first installed, but after being repulled it may contain 17.4 and the upgrade between minor versions will be done automatically. Upgrade between major versions require dumping and re-importing data, please follow upgrade requirements on the PostgreSQL documentation.

Steps to reproduce the issue

1. Check README.md

2. Be confused about what version the tag 17-3.5 should provide, which is mentioned to be 17.0

3. Check what gets installed when using tag 17-3.5, and observe it is 17.4, which is different from the documentation

4. Check if database directories were restructured as mentioned in documentation for minor versions

5. Observe that the upgrade was done successfully for minor versions, in spite of what the documentation mentions about upgrades between minor versions

Versions

17-3.5

Additional context

Technically this is not a bug, and it is neither a feature request, so I'm knowingly breaking the rules, but this would not have fitted on the postgres mailing list, or stackexchange either, as it is very much specific to this very github repository, even specific to a few lines of a file whose truth source is this repository. I believe it may alienate possible contributors to not welcome such reports, even if they're merely about documentation.

[nydydn]

Thank you for confirming. I will do a PR with the documentation changes soon, hopefully later today.

But since this issue is now covering not just the documentation, but also the flexibility of the tag version with respects to minor versions, why do you say that it is not appropriate to only stick to major versions, but allow seamless updates between minor versions with a simple repull?

I personally see it as feature, not a bug. Or do you mean that beside tags like 17-3.5, there should also be tags with 17.0-3.5, 17.1-3.5, 17.2-3.5, etc.?

In my opinion, the recommendation should still be to use the more generic tag 17-3.5, as it currently is, but I agree that having the possibility to really stick to a very specific version would be valuable.

On this note, I think that ideally there should also be a version that doesn't pin the postgis minor version, so perhaps there should also be a tag named 17-3, which would currently provide postgis 3.6. As of now postgis 3.6 is only available under the tag 18-3.6, but I couldn't find a hard restriction on this from postgis. Perhaps there are technical reasons why this might be possible, but not worth it, but I find it worthy for it to be documented, even if just through this issue.

So, is there a technical, or design reason reason for the lack of flexible tags on both PostgreSQL and PostGis (eg 17-3), or is it just that it's never been done because nobody needed it?

[NyakudyaA]

Thank you for confirming. I will do a PR with the documentation changes soon, hopefully later today.

But since this issue is now covering not just the documentation, but also the flexibility of the tag version with respects to minor versions, why do you say that it is not appropriate to only stick to major versions, but allow seamless updates between minor versions with a simple repull?

I personally see it as feature, not a bug. Or do you mean that beside tags like 17-3.5, there should also be tags with 17.0-3.5, 17.1-3.5, 17.2-3.5, etc.?

Yes exactly, this will make it more explicit. So in theory we could have the following published

• 17-3.5 > A user doesn't really care about what minor version exists
• 17.0-3.5 > A user really want's to use that specific version

The main question becomes the change log between versions i.e 17.0 and 17.1 are they significant to warrant publication of a separate tag. If so we publish a new tag otherwise we could litterary keep it as it is and just annotate the README

In my opinion, the recommendation should still be to use the more generic tag 17-3.5, as it currently is, but I agree that having the possibility to really stick to a very specific version would be valuable.

I don't think there is an extra work really to get this to work

On this note, I think that ideally there should also be a version that doesn't pin the postgis minor version, so perhaps there should also be a tag named 17-3, which would currently provide postgis 3.6. As of now postgis 3.6 is only available under the tag 18-3.6, but I couldn't find a hard restriction on this from postgis. Perhaps there are technical reasons why this might be possible, but not worth it, but I find it worthy for it to be documented, even if just through this issue.

We tend not to spend a lot of time back porting versions as this is a community thing. I am sure we could add some magic to the github workflow to fix this.

So, is there a technical, or design reason reason for the lack of flexible tags on both PostgreSQL and PostGis (eg 17-3), or is it just that it's never been done because nobody needed it?

It has never been done