Document how to use custom mbed-os version in platformio

[douardda]

No description provided.

[CLAassistant]

All committers have signed the CLA.

[maxgerhardt]

I'd change this wording to something like "PlatformIO only has certain versions of mbed-os in the official package package registry, as queryable through the API", just to give people a pointer as to where to find natively supported versions.

[maxgerhardt]

The general problem with telling people how to use custom versions is that they then think

1. Using custom mbed-os versions like that is officially supported by PlatformIO staff (there's a "no beta software supported" policy, and one can think of "beta" as "outside of official PlatformIO repositories" here)
2. That it will always work without problems, when e.g. for 6.15.0 it does not because as outlined of a Python dependency missing out-of-the box. People would then have to have a slightly deeper PlatformIO knowledge to understand where the Python / pip installation that PlatformIO is using is and fixup that. And if the builder script starts to fail for newer mbed-os versions because they changed their build API, it's going to be even more complicated for non-staff to fix it. The documentation does not mention all these caveats.

This is definitely useful information for many people, but having it in official docs would give a false sense of "this always works, just do that".

[maxgerhardt]

slight typo in ca -> can here

[maxgerhardt]

1. configuration is missing board = ... line to make it complete, does not mention to add it
2. Maybe general link to https://docs.platformio.org/en/latest/projectconf/section_env_platform.html#platform-packages would be good

[douardda]

Thanks a lot @maxgerhardt I'll try to address your comments ASAP.

[douardda]

The general problem with telling people how to use custom versions is that they then think

1. Using custom mbed-os versions like that is officially supported by PlatformIO staff (there's a "no beta software supported" policy, and one can think of "beta" as "outside of official PlatformIO repositories" here)

2. That it will always work without problems, when e.g. for 6.15.0 it does not because [as outlined](https://community.platformio.org/t/support-for-mbed-os-6-stable-and-mature-apis-cloud-services-support-enhancements-to-the-bare-metal-profile/15079/10?u=maxgerhardt) of a Python dependency missing out-of-the box. People would then have to have a slightly deeper PlatformIO knowledge to understand where the Python / pip installation that PlatformIO is using is and fixup that. And if the builder script starts to fail for newer mbed-os versions because they changed their build API, it's going to be even more complicated for non-staff to fix it. The documentation does not mention all these caveats.

This is definitely useful information for many people, but having it in official docs would give a false sense of "this always works, just do that".

I agree and propose to include a big disclamer in this section.

[douardda]

I've updated a bit the PR, hopefully addressing all your comments.

Thanks again.

[mmontag]

Bump...merge this?