PostgreSQL Upgrade Instructions Incomplete

The Docker Compose script was adjusted to use PostgreSQL 13, however when upgrading from a previous Docker Compose script version, extra steps have to be taken to properly migrate the DB contents.

This is also nicely explained somehow in the actual commit: https://github.com/opf/openproject-deploy/blob/stable/12/compose/control/README.md#upgrade

BUT:

These instructions seem nowhere to be found at places where users will actually look for them. Maybe I just was extraordinarily stupid, but I actually had to fetch the link from the already closed issue #13 and manually copy paste it into my browser's address bar to be able to view it... :-( This was only possible because I knew the instructions were there.

How would I be able to find it without that knowledge?

If I read the official docs, I end up at:

https://www.openproject.org/docs/installation-and-operations/operation/upgrading/#compose-based-installation

This just says

Compose-based installation
When using the Compose-based docker installation, you can simply do the following:

docker-compose pull
docker-compose up -d

Please note that you can override the TAG that is used to pull the OpenProject image from the Docker Hub.

...which will probably break the installation completely, as there's no indication for special treatment of the DB.

I might have expected a notice in the OpenProject release notes, but neither on

https://www.openproject.org/docs/release-notes/12-0-0/#drop-official-support-for-postgresql--13

nor on

https://www.openproject.org/docs/release-notes/12-0-0/#migrating-to-openproject-120 is there any indication that anything special has to be done.

And even if I find the OpenProject Docker Compose GitHub repo and view the instructions there:

https://github.com/opf/openproject-deploy/tree/stable/12/compose

there's not even a hint that anything has to be done manually to the DB.

The instructions only state:

Upgrade
Go to the compose folder:

cd openproject/compose
Retrieve any changes from the openproject-deploy repository:

git pull origin stable/12
Make sure you are using the latest version of the Docker images:

docker-compose pull
Relaunch the containers:

docker-compose up -d

...which will probably also break the installation.

How am I, as a "regular" user, supposed to find the proper upgrade instructions?

IMHO, this should be one of the first things pointed out in any upgrade instructions for OpenProject 12 Docker Compose based installations, and should be REALLY EASY to find and REALLY DIFFICULT to miss.

The current situation is completely the opposite from my point of view - the correct instructions seem to be nearly impossible to find while and official, reachable upgrade instructions seem to indicate that nothing special needs to be done at all...

Start with stable/12/compose/control/README.md and the Compose-based installation upgrade section in the official documentation. Compare those instructions with the PostgreSQL migration steps linked from the issue and the relevant release notes. Done means users can find prominent, consistent upgrade guidance, including the required database migration steps.