Please provide better upgrade instructions between major versions

[Harel M]

Describe the bug
Every time I need to upgrade my local instance of graphhopper I need to reverse engineer the changes that I need to do to the config file in order to make the latest released version work.
While I understand there are a lot of possible configuration the release notes are not helpful in understanding how thing changed and how to make them align with the recent changes.

To Reproduce

Try running import with the version 8 and the following config

Instead of a manual reproduction it would be even better to have a unit or integration test reproducing the issue.
gh-config.txt

Expected behavior

While the error message is helpful to a certain degree, I still need to dig in the release notes to understand what to change, and usually, there's not enough info there.

System Information

Using the 8.0 docker image.

Screenshots & Logs

2024-03-17 06:50:44.998 [main] INFO  com.graphhopper.GraphHopper - version 8.0|2023-10-18T01:57:57Z (9,21,6,5,2,9)
java.lang.IllegalArgumentException: Could not create weighting for profile: 'mtb'.
Profile: name=mtb|vehicle=mtb|weighting=short_fastest|turnCosts=false|hints={}
Error: Instead of weighting=short_fastest use weighting=custom with a distance_influence
        at com.graphhopper.GraphHopper.checkProfilesConsistency(GraphHopper.java:1122)
        at com.graphhopper.GraphHopper.process(GraphHopper.java:881)
        at com.graphhopper.GraphHopper.importAndClose(GraphHopper.java:853)
        at com.graphhopper.application.cli.ImportCommand.run(ImportCommand.java:36)
        at com.graphhopper.application.cli.ImportCommand.run(ImportCommand.java:27)
        at io.dropwizard.cli.ConfiguredCommand.run(ConfiguredCommand.java:98)
        at io.dropwizard.cli.Cli.run(Cli.java:78)
        at io.dropwizard.Application.run(Application.java:94)
        at com.graphhopper.application.GraphHopperApplication.main(GraphHopperApplication.java:38)

I'm not expecting an upgrade tool, although it can be very helpful, just better definition of breaking changes in the github release s page and telling me what is the equivalent of things that are no longer supported.

[Peter]

This is tricky if you already know all the details. So here it would be nice to get contributions from the community and improve the situation where necessary. In this specific case you create a custom model with an appropriate distance_influence, where "appropriate" depends on the profile. E.g. for outdoor profiles we use 5 in production.

I'm not expecting an upgrade tool

We won't need this for every release and won't be able to create tools like this, but we already did something like this in the past.

[Harel M]

The problem was not with the custom model, this was upgraded without any issues.
The problem was with mtb profile and short_fastest model.
If short_fastest was removed I think a proper note in the version release would help here.
The problem with community help here, is that I don't know what's the right way to fix the problem.
I ended up removing short fastest and add an empty array for custom model files.
See here:
IsraelHikingMap/Site@7a96a8a
(Ignore the 20 to 2 change in the 4wd as it's a different issue)

[Andi]

We use the forum to answer questions about version upgrades etc. If you wrote down other things you already figured out yourself it might still be useful for others.

[Peter]

I ended up removing short fastest and add an empty array for custom model files.

You can do that and for mtb it should be fine.

What I meant is a config like this:

   - name: mtb
     vehicle: mtb
     weighting: custom
     custom_model:
        distance_influence: 5

[Harel M]

@easbar the idea behind this issue is not about fixing my issue, I know I can use the forum, which is a great tool, and I know you guys are watching it and answering there, so thanks!
The idea behind this issue is to bring into your attention that some forum question can be avoided given a proper upgrade instruction, taking into consideration the things you removed/broke when decided to create a new major version release with breaking changes (which I obviously understand the need to create a breaking change version from time to time).

It might be that short_fastest is the only breaking change, I don't know, and I might be braking on the wrong tree.

Regardless, thanks a lot for all the work done on this library! It is truly appreciated.

[Peter]

I agree that we previously always just linked issues which was convenient for us developers but suboptimal for users. The next version will contain a migration guide under docs/migration. Please have a look into #2938 which will be the first to have such a guide (i.e. for version 9.x). It is very likely not complete (please let us know!) and probably a longer learning process on how to do this, but it is a good start to try to have all information in one place.

Regardless, thanks a lot for all the work done on this library! It is truly appreciated.

Thanks!

[Harel M]

Looks good! Thanks! I'll probably need to read it thoroughly when switching to 9 and only then provide a variable feedback, but I think it's an excellent start.