starred/photoprism

Fork 0

mirror of https://github.com/photoprism/photoprism.git synced 2026-03-02 22:57:18 -05:00

Docs: Write detailed upgrade guides for each release #1436

New issue

Open

opened 2026-02-20 00:12:42 -05:00 by deekerman · 5 comments

deekerman commented

2026-02-20 00:12:42 -05:00

Owner

Originally created by @alexislefebvre on GitHub (May 19, 2022).

Is your feature request related to a problem? Please describe.

A config was changed but not explained.

Example:

PHOTOPRISM_DARKTABLE_PRESETS was renamed to PHOTOPRISM_RAW_PRESETS: github.com/photoprism/photoprism@05d39e8c3c

Users who deployed the project before this release have a PHOTOPRISM_DARKTABLE_PRESETS config in their docker-compose.yml files, this value is now obsolete. It can confuse users, for example see https://github.com/photoprism/photoprism/discussions/2206

Other example: MariaDB was upgraded to 10.7: github.com/photoprism/photoprism@36d84de0c4 (diff-e45e45baed)

It is not explained on the pages of releases: https://github.com/photoprism/photoprism/releases or https://docs.photoprism.app/release-notes/

In the long term, if users don't update their config, the config in this repo and the config used by the users will diverge, which may end up in unexpected behaviours.

Describe the solution you'd like

Add instructions to upgrade with the changelog on each release. Or add an upgrade guide in a Markdown file or the documentation.

Examples:

Version x.y.z

What you have to do:

rename PHOTOPRISM_DARKTABLE_PRESETS to PHOTOPRISM_RAW_PRESETS in your docker-compose.yml file

upgrade MariaDB from 10.6 to 10.7 in your docker-compose.yml file and update the variables in the environment section:

[…]

Describe alternatives you've considered

Additional context

Originally created by @alexislefebvre on GitHub (May 19, 2022). **Is your feature request related to a problem? Please describe.** A config was changed but not explained. Example: `PHOTOPRISM_DARKTABLE_PRESETS` was renamed to `PHOTOPRISM_RAW_PRESETS`: https://github.com/photoprism/photoprism/commit/05d39e8c3c8fd1e4f83563786aa05c115f7dc5b7 Users who deployed the project before this release have a `PHOTOPRISM_DARKTABLE_PRESETS` config in their `docker-compose.yml` files, this value is now obsolete. It can confuse users, for example see https://github.com/photoprism/photoprism/discussions/2206 Other example: MariaDB was upgraded to 10.7: https://github.com/photoprism/photoprism/commit/36d84de0c406365fcf1a4e21b071b5ef7dfb2049#diff-e45e45baeda1c1e73482975a664062aa56f20c03dd9d64a827aba57775bed0d3 It is not explained on the pages of releases: https://github.com/photoprism/photoprism/releases or https://docs.photoprism.app/release-notes/ In the long term, if users don't update their config, the config in this repo and the config used by the users will diverge, which may end up in unexpected behaviours. **Describe the solution you'd like** Add instructions to upgrade with the changelog on each release. Or add an upgrade guide in a Markdown file or the documentation. Examples: > ### Version x.y.z > What you have to do: > - rename `PHOTOPRISM_DARKTABLE_PRESETS` to `PHOTOPRISM_RAW_PRESETS` in your `docker-compose.yml` file > - upgrade MariaDB from `10.6` to `10.7` in your `docker-compose.yml` file and update the variables in the `environment` section: > - […] **Describe alternatives you've considered** . **Additional context** .

deekerman added the

idea

help wanted

docs 📚

labels

2026-02-20 00:12:42 -05:00

deekerman commented

2026-02-20 00:12:43 -05:00

Author

Owner

@lastzero commented on GitHub (May 19, 2022):

Config Options, Supported Formats and Features

As for general documentation of parameters and features, we have added a knowledge base to our website and added commands that will automatically provide you with this information as part of our latest release:

https://photoprism.app/kb

That's more than most open source projects and proprietary software vendors offer, and you can create a diff to keep up with every detail that changes. Our Community Edition will continue to be a rolling release without SemVer and enterprise grade migration guides.

We may change this later and provide more detail if requested, but right now we can't afford to do that if we are to release all the features the community wants with the current budget. Contributors are welcome to take on the work of writing such upgrade guides.

MariaDB

MariaDB is simply the latest stable version with the improvements you can find in the MariaDB Release Notes. We have added an environment variable that automatically updates the MariaDB schema version, so no manual intervention is required.

I see little purpose in writing a text explaining why it makes sense to use this or any other version: It is the version we are currently using for development and with which the release is tested by us. If for some reason users want to keep an old version, they are free to do so at their own risk.

@lastzero commented on GitHub (May 19, 2022): ## Config Options, Supported Formats and Features ## As for general documentation of parameters and features, we have added a knowledge base to our website and added commands that will automatically provide you with this information as part of our latest release: - https://photoprism.app/kb That's more than most open source projects and proprietary software vendors offer, and you can create a diff to keep up with every detail that changes. Our Community Edition will continue to be a rolling release without SemVer and enterprise grade migration guides. We may change this later and provide more detail if requested, but right now we can't afford to do that if we are to release all the features the community wants with the current budget. **Contributors are welcome to take on the work of writing such upgrade guides.** ## MariaDB ## MariaDB is simply the latest stable version with the improvements you can find in the MariaDB Release Notes. We have added an environment variable that automatically updates the MariaDB schema version, so no manual intervention is required. I see little purpose in writing a text explaining why it makes sense to use this or any other version: It is the version we are currently using for development and with which the release is tested by us. If for some reason users want to keep an old version, they are free to do so at their own risk.

deekerman commented

2026-02-20 00:12:43 -05:00

Author

Owner

@alexislefebvre commented on GitHub (May 19, 2022):

Thanks for your answer.

A diff is too huge to read, the last one contains 589 commits 1003 files changed: https://github.com/photoprism/photoprism/compare/220302-0059f429...220517-b9c68f8f

The next time that I upgrade Photoprism, I'll check the changes on the release page and compare my docker-compose.yml with the current one. It should be enough to keep my instance up-to-date.

If my issue was unclear, Symfony provides a good example of a good changelog, it explains what has been removed, with replacements when they are available.

@alexislefebvre commented on GitHub (May 19, 2022): Thanks for your answer. A diff is too huge to read, the last one contains 589 commits 1003 files changed: https://github.com/photoprism/photoprism/compare/220302-0059f429...220517-b9c68f8f The next time that I upgrade Photoprism, I'll check the changes on the release page and compare my `docker-compose.yml` with the [current one](https://github.com/photoprism/photoprism/blob/develop/docker/examples/docker-compose.yml). It should be enough to keep my instance up-to-date. If my issue was unclear, Symfony provides a good example of a [good changelog](https://github.com/symfony/framework-bundle/blob/6.0/CHANGELOG.md#changelog), it explains what has been removed, with replacements when they are available.

deekerman commented

2026-02-20 00:12:43 -05:00

Author

Owner

@lastzero commented on GitHub (May 19, 2022):

Seems you got this wrong, I meant a diff of the newly added "photoprism show" commands which now always show the currently supported options, features and formats. Not a full git diff! 😜

The raw variable should have better communicated and updated in the examples, no doubt about it. But it's not like we constantly change options and break stuff. The only reason this happend is because we have too much work and I simply forgot, probably assuming this was already done or I discussed it personally with only a few people in the chat. Could have happened with any type of release and upgrade notes.

Be aware Symfony has much greater resources, so you can't just ask us to do the same. We completely agree it would be great to have even better docs, thus we have marked this issue as "help wanted".

By the way, your feedback is greatly appreciated by us! I'm traveling today and have to answer most questions on my mobile phone, so can't edit my answers back and forth to always hit the right tone and go into all details.

@lastzero commented on GitHub (May 19, 2022): Seems you got this wrong, I meant a diff of the newly added "photoprism show" commands which now always show the currently supported options, features and formats. Not a full git diff! 😜 The raw variable should have better communicated and updated in the examples, no doubt about it. But it's not like we constantly change options and break stuff. The only reason this happend is because we have too much work and I simply forgot, probably assuming this was already done or I discussed it personally with only a few people in the chat. Could have happened with any type of release and upgrade notes. Be aware Symfony has much greater resources, so you can't just ask us to do the same. We completely agree it would be great to have even better docs, thus we have marked this issue as "help wanted". By the way, your feedback is greatly appreciated by us! I'm traveling today and have to answer most questions on my mobile phone, so can't edit my answers back and forth to always hit the right tone and go into all details.

deekerman commented

2026-02-20 00:12:43 -05:00

Author

Owner

@lastzero commented on GitHub (May 20, 2022):

While this can't completely replace handwritten docs, the new "show" commands provide an easy way to see the available options, including a description, in a variety of formats that can be easily compared:

This is work in progress. A future version might even be able to generate upgrade docs with detailed comparisons, so you don't even have to run diff manually.

@lastzero commented on GitHub (May 20, 2022): While this can't completely replace handwritten docs, the new "show" commands provide an easy way to see the available options, including a description, in a variety of formats that can be easily compared: ![Screenshot 2022-05-20 at 10 12 22](https://user-images.githubusercontent.com/301686/169484476-43c4ad29-8c77-4969-ae71-8efeab79d68f.png) This is work in progress. A future version might even be able to generate upgrade docs with detailed comparisons, so you don't even have to run `diff` manually.

deekerman commented

2026-02-20 00:12:43 -05:00

Author

Owner

@Morl99 commented on GitHub (Jul 16, 2022):

Instead of relying on manually written docs, it could be very helpful to print warnings for all Environment variables that match PHTOPRISM_ but that are not recognized by the current version of photoprism. This will make it really easy to catch configuration bugs, no matter if they originate from a version upgrade or from a simple typo.

@Morl99 commented on GitHub (Jul 16, 2022): Instead of relying on manually written docs, it could be very helpful to print warnings for all Environment variables that match PHTOPRISM_ but that are not recognized by the current version of photoprism. This will make it really easy to catch configuration bugs, no matter if they originate from a version upgrade or from a simple typo.