Add a shared platform support pattern to Apple platforms, Linux, and Windows

[heckj]

Summary

• Adds a ### Platform support subsection to each of apple-platforms/, linux/, and windows/'s Documentation.md, following one shared shape: an SP-0001 tier statement, a minimum version/architecture table, an available-tools note, a platform-owner note, and a closing link to https://www.swift.org/platform-support/ for the full cross-platform comparison.
• None of these three catalogs currently say anything about supported versions, tools, or ownership inside the combined docs build — this fills that gap without duplicating the full multi-platform matrix that already lives on swift.org.
• No changes to scripts/sources.json or scripts/navigation.json; the existing three-catalog wiring under the "Platforms" nav group is unchanged.

Test plan

• swift package generate-documentation --analyze --warnings-as-errors passes in apple-platforms/, linux/, and windows/
• Version/tool facts cross-checked against the live https://www.swift.org/platform-support/ page
• Visually confirm rendering via swift package --disable-sandbox preview-documentation in each catalog

[heckj]

Adding what this looks in the Apple, Linux, and Windows platform pages rendered locally

Apple:

Windows:

Linux:

[finagolfin]

Will Android's status be added to this list on the website somewhere? The Android workgroup submitted our application in January and were told our status was approved soon after, with that to be published on the website sometime later.

[heckj]

(updated Linux content as well to align with swiftlang/swift-org-website#1519)

[heckj]

(once approved, I'll cherry back to release/6.4.x branch in order to reflect this detail at docs.swift.org/latest/documentation)

[davelester]

@heckj Could we revamp the descriptive text for each of the pages, which currently appears as "{platform} is a Tier {#} platform" to something more approachable, and linking to the evolution proposal within the prose instead of calling it out so prominently?

Example:

Linux is a supported platform. The Swift project provides official toolchain builds, so you can both develop and deploy Swift on Linux.

cc @compnerd for feedback as well, given the recent review

[compnerd]

@davelester I think that the tiering is relevant - we want to encourage more platforms to be listed, including non-toolchain-host platforms, and tier 2 platforms. If there is a better way to phrase that, it could be interesting.

[davelester]

@compnerd I agree that tiers are relevant and important. At the same, the tier title (in the case of tier 1, that's "supported platforms") may be more intuitive in the overview section of docs than naming a platform as "tier 1."

Let me know what you think about the example I shared: #132 (comment); it still links to the the evolution proposal with all of the Tier 1 info, it simply uses the title instead of the number.

[compnerd]

Let me know what you think about the example I shared: #132 (comment); it still links to the the evolution proposal with all of the Tier 1 info, it simply uses the title instead of the number.

I don't think that works. Supported means tier 1 hosted, tier 1 unhosted, and tier 2 platforms. That is the problem ultimately, there are gradations of support, and we should indicate what level of support is ascribed to a particular platform.

[davelester]

@compnerd The description I pointed was for the Linux platform overview, which currently does not describe hosted or unhosted; that could easily be added to the a platform description without needing to mention Tier 1. If you still disagree, could you help me understand what is lost?

The main motivation here is to use the tier title to lead with the documentation overview, versus the tier number which is not intuitive to a new reader. Both derive from the same SP-0001 proposal.

[compnerd]

@compnerd The description I pointed was for the Linux platform overview, which currently does not describe hosted or unhosted; that could easily be added to the a platform description without needing to mention Tier 1. If you still disagree, could you help me understand what is lost?

I missed that, we should be indicating that Linux x64 and arm64 are hosted platforms, but Linux armv7 and x86 are not.

Tier 1 indicates that we expect all the tests to be passing in CI, tier 2 indicates that the tests may be failing at any given point. This is important when you use a snapshot. That loss of information is important. Listing the literal "tier \d" is not the critical aspect, but rather the fact that it implies testing levels is (I don't like the idea of "this is supported but untested" as what we describe the supported platforms).

[shahmishal]

is the goal to replace https://www.swift.org/platform-support/ with this docs?

[al45tair]

Looks good; I think we should note that Linux is also a toolchain host.

[al45tair]

is the goal to replace https://www.swift.org/platform-support/ with this docs?

I think so, yes. It would be worth checking that we have all of the information from that page before actually removing it, mind.

[FranzBusch]

General question do we think it is good to separate out each platform into a separate doc page instead of providing one page that has an overview similar to https://doc.rust-lang.org/rustc/platform-support.html ? I find there is a lot of value in having an information dense page like the Rust one provides.

[heckj]

@FranzBusch I asked the same questions when setting this up, and I think generally it makes the most sense. A single page with all details, especially with support that's expanding, can get unwieldy quickly when you get more items on it - we're not entirely there, but pretty much at the edge of it. Splitting it up by platform lets us cover the data, albeit in not as consolidated a fashion, and provides a place to offer deeper dives that are specific to Swift and [XYZ] platform to link forward and provide pathways for developers who are interested in developing on, or hosting on, those platforms. So I think this is the right structure overall.

I'll caveat that with saying that it would be really great to a single, clear page that lays out the SP-001 support and tier concepts, and that's something we don't have right now

[heckj]

@al45tair @shahmishal that was the general gist (to replace https://www.swift.org/platform-support/) - to shift that concept about support, which isn't linked directly in the updated swift.org design setup, into the "documentation" for Swift.