Backward-compatibilty for forecasting/ingestion endpoints, QA workflow works with older clients

[nhoening]

Description

We want to ensure backward-compatibility with older clients also for forecasting and data ingestion endoints which went to the 202 route. Their function would still work as normal, but fm-clients expect not just 2xx but specifically 200 and could break flows on the client side.

This PR dos that, and also improves the ability to signal legancy clients on assets or per QA run, and works on the QA/Release workflow to let us test legacy clients there.

• add beackwards-compatible responses also for forecasting and ingestion (basically let them respond with 200 as before, ingestion would also stop being asynchronous), so older clients can get the responses they expect.
• The legacy clients are adhered to with the asset attribute we introduced in fix: keep legacy 200/400 codes for older clients in schedule-related endpoints #2429. It is now renamed to indicate its wider scope and it can also be forced from config withut altering assets (only to be used in QA)
• skip steps that older versions are not be able to run, like the ingestion tutorial or HEMS script - or enable them in QA/Release workflow if possible.
• installation of packaged clients works differently than from branches
• our recent work on backwards-compatibility should be baked into the FM assets / config we run
• Added changelog item in documentation/changelog.rst

Here is an overview over the features we are now testing with legacy clients:

Client	Ingestion	Forecasting	Scheduling	Reporting
main	✅ API: file + JSON + read-back	✅ API via HEMS	✅ API: trigger + retrieve via HEMS	⚠️ CLI only
v0.9.4	✅ API: file + JSON + read-back	✅ API via HEMS	✅ API: trigger + retrieve via HEMS	⚠️ CLI only
v0.9.0	✅ API: file + JSON + read-back	✅ API via HEMS¹	✅ API: trigger + retrieve via HEMS¹	⚠️ CLI only
v0.8.0	✅ API: file + JSON + read-back	🚫 No client API²	🧪 API: trigger + retrieve via HEMS¹	⚠️ CLI only²
v0.7.0	✅ API: JSON + read-back³	🚫 No client API	❌ Not covered⁴	🚫 No client API

• ✅ Client API compatibility is tested.
• 🧪 Coverage is implemented; successful workflow run still needs confirmation.
• ⚠️ Exercised through the server CLI, not through a client API.
• ❌ Potentially supported, but not covered by this workflow.
• 🚫 The relevant client API did not exist.

1. Uses legacy job-response compatibility.
2. Client has no forecasting and/or reporting support yet. HEMS exercises the server CLI, but this does not test a client API.
3. Uses legacy post_measurements(); file ingestion is unavailable.
4. v0.7.0 has no HEMS example, so scheduling is not exercised.

The server CLI tutorials run in every workflow, but they are not counted as client backward-compatibility coverage.

How to test

Run the QA/release workflow with this branch, and try various client versions or branches

I ran these fm-clients successfully:

• main
• v0.9.4
• v0.9.0
• v0.8.0
• v0.7.0

Note: 0.7.0 has no HEMS script yet, as mentioned above.

Here is example output (from the Determine client QA capabilities):

=== Client QA plan ===
Requested client ref:              v0.8.0
Resolved client version:           0.8.0
Client source:                     PyPI release package
Data-ingestion tutorial:           true
HEMS example:                      true
Legacy job responses:              true
Legacy CLI wrapper:                true
v0.8.0 HEMS simulation shim:       true
Ingestion API support:             yes (file and JSON uploads)
Planned client ingestion:          API file and JSON uploads with read-back (tutorial)
Forecasting API support:           no
Planned client forecasting:        server CLI (HEMS; no client API)
Scheduling API support:            yes
Planned client scheduling:         API trigger and power/SoC retrieval (HEMS)
Reporting API support:             no (planned for FlexMeasures 1.1)
Planned client reporting:          server CLI (HEMS; no client API)
Server CLI tutorials 1-5:          run (not client-specific)
==============================

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #34241955 | 📁 Comparing fc3fb4c against latest (3272084)

  🔍 Preview build  

10 files changed · + 1 added · ± 9 modified

+ Added

• _autosummary/flexmeasures.api.v3_0.utils.html

± Modified

• changelog.html
• configuration.html
• genindex.html
• py-modindex.html
• _autosummary/flexmeasures.api.common.utils.api_utils.html
• _autosummary/flexmeasures.api.v3_0.html
• api/change_log.html
• api/v3_0.html
• tut/posting_data.html

[BelhsanHmida]

LGTM, @nhoening one question before I sign off.

The PR renames FLEXMEASURES_LEGACY_SCHEDULEACCEPTED_STATUS_MAX_INCOMPATIBLE_CLIENT_VERSION to FLEXMEASURES_LEGACY_JOB_RESPONSES_MAX_INCOMPATIBLE_CLIENT_VERSION. The old name shipped in rc5, tagged 20 Aug six days. FlexMeasures doesn't report unknown settings at startup, so anyone who configured the old name silently drops back to 202 responses on upgrade, for exactly the clients the setting protects.

I pushed 01c899b for that, which reads the old name as a fallback and logs a deprecation warning. I also have a revert ready locally, since six days in one rc may be thin grounds for carrying a deprecated alias into 1.0. Should I push the revert, or leave the fallback in? Comes down to whether any deployment actually set the old name during rc5.

[nhoening]

Thanks @BelhsanHmida .
That is the one I also thought about.
I vote for the revert. The price of added code weighs heavier for me. And it was not an official release yet.