Update compose file docs

[robertgzr]

Occasionally users try to use fields that are supported by v2 but have
different properties in version 3 (like long syntax for ports) and
are surprised to get an error in response.
Clarify that our support is based on version 2.4

Change-type: patch
Signed-off-by: Robert Günzler [email protected]

[klutchell]

Do we actually support v2.4 fully? Why can't I put version: "2.4" at the top of my compose file, is it just a CLI bug?

[robertgzr]

@klutchell hmm how did you try? balena push?

[klutchell]

@robertgzr yeah, I get Unsupported composition version so it might need updating in the CLI

[robertgzr]

@klutchell oohh yes definitely... see the hq issue for the list of todos

[klutchell]

Should we wait to merge this until all of the related 2.4 support PRs have merged in the CLI, etc?

[robertgzr]

will remove the draft label when builder and cli changes are merged (deployed?)

[robertgzr]

• update section on build.network being disallowed

[vipulgupta2048]

@robertgzr Hey, what if we can automate this page to generate documentation as per the version we support? Can we do that if it is possible?

[robertgzr]

@vipulgupta2048 I'm not sure about that. Right now the properties we do and don't support result from our code in compose-parse, with the actual implementation scattered between multibuild (for buildtime) and supervisor (for runtime)

and sometimes there is partial support (like with depends_on introduced here)

maybe we can express the information that is needed here in a json schema form though? we already kind of use one...

[robertgzr]

another thing that came to mind is where this documentation actually appears. It's not obvious to me why it's part of the supervisor reference, since it matters at build time as well (which is more cloud/cli doc)

[vipulgupta2048]

Oh wow, this got left behind quite a bit @robertgzr
Can you add #2189 to this PR and we can finish this.

My automation request was a more of a suggestion, although maybe the engine should have a contract of what properties it supports to help list things out in a better way.

[robertgzr]

@vipulgupta2048 you can check https://github.com/balena-io/balena-io/issues/2311#issuecomment-931564390, this work is stalled until I or somebody finds the time to investigate the breakage we get from using livepush with target directive

we should keep this PR open until those things are all completed I think...

[dfunckt]

@balena-ci rebase