Add a new document for choosing toolchains for workflows #369
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
heckj
reviewed
May 29, 2025
There was a problem hiding this comment.
I swept through with a pretty heavy "red pen", suggesting alternatives in lots of places. I suspect you might be trying to tackle too much in a single article - I'd describe the focus as on .swift-version and how swiftly uses it, and the benefits of having a standard/convention for recording and reading this information that spans tools. The lower section of the article also dives into versions specified elsewhere, describes their purpose (the Swift language tools version in Package.swift and the language mode declaration inside the manifest of recent versions of PackageDescription), but it felt a bit muddled - like you were going afield to explain what those other pieces are when the article was otherwise focused on how to document, choose, and run aspects of your project with specific toolchain versions.
As always feel free to disregard my suggestions - most of them were focused on reframing to active voice, or shortening/removing extraneous sections of sentences to tighten up the point. A few minor typos here and there, or missing word in the mix as well.
There's still a number of places with passive voice - a lot of the overall tone was more indirect and making the argument for this. I think this'll be better off with a focus on what it does, highlighting the problems it helps solve, and how you use it. That's completely a style and voice call.
|
|
||
| ## Overview | ||
|
|
||
| Swift toolchains include a variety of tools for building, testing, debugging, formatting code, and IDE integration. There's also a set of foundational libraries in a toolchain that can have an impact to the way that your code builds and runs. All of these things have an impact on the development of your project. |
There was a problem hiding this comment.
Suggested change
| Swift toolchains include a variety of tools for building, testing, debugging, formatting code, and IDE integration. There's also a set of foundational libraries in a toolchain that can have an impact to the way that your code builds and runs. All of these things have an impact on the development of your project. | |
| Swift toolchains include a variety of tools for building, testing, debugging, formatting code, and IDE integration. There's also a set of foundational libraries in a toolchain that can affect the way that your code builds and runs. All of these have an impact on the development of your project. |
|
|
||
| ### Getting started working on a project | ||
|
|
||
| When you're working on a particular project, such as developing a bug fix, or adding a feature, you'll want the toolchain that sets you up on a path to successfully getting your pull request merged at that point in time. Along the way, you are likely to need a toolchain that will successfully compie the code with the language features that it requires, and is also unlikely to have show-stopping problems in doing that. |
There was a problem hiding this comment.
Suggested change
| When you're working on a particular project, such as developing a bug fix, or adding a feature, you'll want the toolchain that sets you up on a path to successfully getting your pull request merged at that point in time. Along the way, you are likely to need a toolchain that will successfully compie the code with the language features that it requires, and is also unlikely to have show-stopping problems in doing that. | |
| When you're working on a particular project, such as developing a bug fix, or adding a feature, you'll want the toolchain that helps you get your pull request merged. Along the way, you need a toolchain that successfully compiles the code; one that has the language features the code requires. |
tried to tighten the sentence up a bit, without loosing anything critical
|
|
||
| When you're working on a particular project, such as developing a bug fix, or adding a feature, you'll want the toolchain that sets you up on a path to successfully getting your pull request merged at that point in time. Along the way, you are likely to need a toolchain that will successfully compie the code with the language features that it requires, and is also unlikely to have show-stopping problems in doing that. | ||
|
|
||
| Iterating on this code might involve using a supported IDE, such as VS Code, that makes use of a matching language server (sourcekit-lsp) that works with this code. Perhaps the code base uses certain features from Swift Testing, only available starting in a particular release. The version of swift-format can also have an impact on the formatting (and the formatting checks) on the code, so it will save time and increase confidence when formatting your new code to use the correct version. A developer would like the version that's most likely to succeed in all of these areas. |
There was a problem hiding this comment.
Suggested change
| Iterating on this code might involve using a supported IDE, such as VS Code, that makes use of a matching language server (sourcekit-lsp) that works with this code. Perhaps the code base uses certain features from Swift Testing, only available starting in a particular release. The version of swift-format can also have an impact on the formatting (and the formatting checks) on the code, so it will save time and increase confidence when formatting your new code to use the correct version. A developer would like the version that's most likely to succeed in all of these areas. | |
| Iterating on this code might involve using a supported IDE, such as VS Code, that makes use of a matching language server, such as sourcekit-lsp. Perhaps the code base uses features from Swift Testing that only available starting in a particular release. The version of swift-format can also have an impact on the code formatting and formatting checks, so it will save time and increase confidence when formatting your updates to the code. A developer would like the version that's most likely to succeed in all of these areas. |
mostly just tightening the wording
|
|
||
| Iterating on this code might involve using a supported IDE, such as VS Code, that makes use of a matching language server (sourcekit-lsp) that works with this code. Perhaps the code base uses certain features from Swift Testing, only available starting in a particular release. The version of swift-format can also have an impact on the formatting (and the formatting checks) on the code, so it will save time and increase confidence when formatting your new code to use the correct version. A developer would like the version that's most likely to succeed in all of these areas. | ||
|
|
||
| A project can publish the recommended default version of the specific toolchain in their developer's guide. This is a good start, and helps someone to get started with a good chance of success. Documention is often a worthwhile investment, but sometimes we can do better with tooling. |
There was a problem hiding this comment.
Do you want to mention looking at the minimum required tools version in the Package.swift manifest? Using that as a baseline "lower boundary"?
|
|
||
| ### Verifying a project | ||
|
|
||
| When verifying a project in something like a CI system, it's important to pick a toolchain that meets the objective of verifying that the current state of the code with a level of reliability. Using the [test pyramid](https://martinfowler.com/articles/practical-test-pyramid.html) model, you want to get the *majority* of tests running _quickly_, but also *reliably*. |
There was a problem hiding this comment.
Suggested change
| When verifying a project in something like a CI system, it's important to pick a toolchain that meets the objective of verifying that the current state of the code with a level of reliability. Using the [test pyramid](https://martinfowler.com/articles/practical-test-pyramid.html) model, you want to get the *majority* of tests running _quickly_, but also *reliably*. | |
| When verifying a project, for example using continuous integration, it's important to pick a toolchain that meets verifies the current state of the code with a level of reliability. Using the [test pyramid](https://martinfowler.com/articles/practical-test-pyramid.html) model, you want to get the *majority* of tests running _quickly_, and also *reliably*. |
foo is visually identical to foo - did you mean for the reliably above to be bold? (reliably)
| ``` | ||
| Package( | ||
| name: "foo", | ||
| swiftLanguageVersions: [v5, v6] |
There was a problem hiding this comment.
Suggested change
| swiftLanguageVersions: [v5, v6] | |
| swiftLanguageMode: [v5, v6] |
swiftLanguageVersion was created and quickly deprecated
| ) | ||
| ``` | ||
|
|
||
| This version is used to set the supported language modes in the Swift compiler because it can support handling source code from much older, and newer versions of the language. This has little to do with the recommended toolchain version to use for a project, and is much more about supporting legacy Swift code. There are similar settings for the C, and C++ language standards used by clang. |
There was a problem hiding this comment.
Suggested change
| This version is used to set the supported language modes in the Swift compiler because it can support handling source code from much older, and newer versions of the language. This has little to do with the recommended toolchain version to use for a project, and is much more about supporting legacy Swift code. There are similar settings for the C, and C++ language standards used by clang. | |
| This declares the supported language modes for the Swift compiler, as it supports older and newer versions of the language. This has little to do with the recommended toolchain version, and is more about supporting legacy Swift code. There are similar settings for the C, and C++ language standards used by clang. |
|
|
||
| This version is used to set the supported language modes in the Swift compiler because it can support handling source code from much older, and newer versions of the language. This has little to do with the recommended toolchain version to use for a project, and is much more about supporting legacy Swift code. There are similar settings for the C, and C++ language standards used by clang. | ||
|
|
||
| Newer toolchains can support much older language versions. For Swift versions, they tend to be only the major version, not the minor, and patch versions that uniquely identify an exact recommended toolchain. |
There was a problem hiding this comment.
Suggested change
| Newer toolchains can support much older language versions. For Swift versions, they tend to be only the major version, not the minor, and patch versions that uniquely identify an exact recommended toolchain. |
I think I'd drop this completely - the definition of what language mode is supported is in the docs linked above, and this reads as a repeat of the paragraph above.
|
|
||
| ## Summary | ||
|
|
||
| Depending on your workflow, there is often some kind of recommended toolchain version that can help you to succeed in the primary flow. What's needed is a standard way to record this information. The swift version file is a simple format to document the version. Tooling support, including swiftly, can help you to choose this recommended toolchain across different projects. While there are other sources of version information in Swift projects, they are designed for other things. |
There was a problem hiding this comment.
Suggested change
| Depending on your workflow, there is often some kind of recommended toolchain version that can help you to succeed in the primary flow. What's needed is a standard way to record this information. The swift version file is a simple format to document the version. Tooling support, including swiftly, can help you to choose this recommended toolchain across different projects. While there are other sources of version information in Swift projects, they are designed for other things. | |
| Depending on your workflow, there is often a recommended toolchain version that can help you to succeed. The swift version file is a simple format to document this version, and provides a standard way to record it. Tooling support, including swiftly, helps you to choose this recommended toolchain across different projects. |
Recommend dropping that final sentence, as I think you want to leave the focus on swift-version and how swiftly uses it, rather than trying to disambiguate from the other versions scattered around.
|
|
||
| Depending on your workflow, there is often some kind of recommended toolchain version that can help you to succeed in the primary flow. What's needed is a standard way to record this information. The swift version file is a simple format to document the version. Tooling support, including swiftly, can help you to choose this recommended toolchain across different projects. While there are other sources of version information in Swift projects, they are designed for other things. | ||
|
|
||
| Having a single recommended version doesn't prevent you from using other toolchain versions for various purposes. There is room within the test pyramid model for integration testing with alternate versions. Swiftly has some mechanisms, such as the `swiftly run` version selector syntax, to automate testing with older and newer versions to support this style of integration testing, as well ad-hoc explorations too. |
There was a problem hiding this comment.
Suggested change
| Having a single recommended version doesn't prevent you from using other toolchain versions for various purposes. There is room within the test pyramid model for integration testing with alternate versions. Swiftly has some mechanisms, such as the `swiftly run` version selector syntax, to automate testing with older and newer versions to support this style of integration testing, as well ad-hoc explorations too. | |
| Having a single recommended version doesn't prevent you from using other toolchain versions. For example, the test pyramid model highlights integration testing with alternate versions. Swiftly provides the `swiftly run` version selector syntax to automate testing with older and newer versions, as well ad-hoc explorations too. |
plemarquand
reviewed
May 29, 2025
|
|
||
| ## Overview | ||
|
|
||
| Swift toolchains include a variety of tools for building, testing, debugging, formatting code, and IDE integration. There's also a set of foundational libraries in a toolchain that can have an impact to the way that your code builds and runs. All of these things have an impact on the development of your project. |
There was a problem hiding this comment.
Suggested change
| Swift toolchains include a variety of tools for building, testing, debugging, formatting code, and IDE integration. There's also a set of foundational libraries in a toolchain that can have an impact to the way that your code builds and runs. All of these things have an impact on the development of your project. | |
| In addition to the Swift compiler, Swift toolchains include a variety of tools for building, testing, debugging, formatting code, and integrating with IDEs. They also contain foundational libraries that can have an impact on the way that your code builds and runs. |
|
|
||
| Swift toolchains include a variety of tools for building, testing, debugging, formatting code, and IDE integration. There's also a set of foundational libraries in a toolchain that can have an impact to the way that your code builds and runs. All of these things have an impact on the development of your project. | ||
|
|
||
| Luckily, swiftly exists to make it easy to get a toolchain. Which one of the potentially large number do I pick? This question can be bewildering. |
There was a problem hiding this comment.
Suggested change
| Luckily, swiftly exists to make it easy to get a toolchain. Which one of the potentially large number do I pick? This question can be bewildering. | |
| Luckily, swiftly exists to make it easy to get a toolchain. How do you decide which one to pick? |
|
|
||
| ### Getting started working on a project | ||
|
|
||
| When you're working on a particular project, such as developing a bug fix, or adding a feature, you'll want the toolchain that sets you up on a path to successfully getting your pull request merged at that point in time. Along the way, you are likely to need a toolchain that will successfully compie the code with the language features that it requires, and is also unlikely to have show-stopping problems in doing that. |
There was a problem hiding this comment.
Suggested change
| When you're working on a particular project, such as developing a bug fix, or adding a feature, you'll want the toolchain that sets you up on a path to successfully getting your pull request merged at that point in time. Along the way, you are likely to need a toolchain that will successfully compie the code with the language features that it requires, and is also unlikely to have show-stopping problems in doing that. | |
| When you're working on a particular project, such as developing a bug fix or adding a feature, you'll want the toolchain that sets you up on a path to successfully getting your pull request merged. Along the way, you'll likely need a toolchain that will successfully compile the code with the language features that it requires, and is also unlikely to have show-stopping problems in doing that. |
|
|
||
| ### Getting started working on a project | ||
|
|
||
| When you're working on a particular project, such as developing a bug fix, or adding a feature, you'll want the toolchain that sets you up on a path to successfully getting your pull request merged at that point in time. Along the way, you are likely to need a toolchain that will successfully compie the code with the language features that it requires, and is also unlikely to have show-stopping problems in doing that. |
There was a problem hiding this comment.
I think this section is a bit verbose and doesn't reflect what I do when I start working on a new project which is:
- If there is a .swift-version file, I use that to determine what toolchain to download
- check the README or any other documentation of the package
- Finally check the tools version in the Package.swift and I use that version
|
|
||
| When verifying a project in something like a CI system, it's important to pick a toolchain that meets the objective of verifying that the current state of the code with a level of reliability. Using the [test pyramid](https://martinfowler.com/articles/practical-test-pyramid.html) model, you want to get the *majority* of tests running _quickly_, but also *reliably*. | ||
|
|
||
| Reliability in toolchain selection is knowing which toolchain has produced good results in the pastat a developer's desk, better would be to use one that's been verified in CI. And so, maybe the CI system uses the toolchain that's documented in the developer's guide? It can be a manual process, such as when the developer's guide is updated. Better would be to have some tooling support that handles both develpers getting started and toolchain selection in CI. In any case swiftly can help install the chosen default toolchain. |
There was a problem hiding this comment.
Suggested change
| Reliability in toolchain selection is knowing which toolchain has produced good results in the pastat a developer's desk, better would be to use one that's been verified in CI. And so, maybe the CI system uses the toolchain that's documented in the developer's guide? It can be a manual process, such as when the developer's guide is updated. Better would be to have some tooling support that handles both develpers getting started and toolchain selection in CI. In any case swiftly can help install the chosen default toolchain. | |
| Reliability in toolchain selection is knowing which toolchain has produced good results in the past at a developer's desk, better would be to use one that's been verified in CI. And so, maybe the CI system uses the toolchain that's documented in the developer's guide? It can be a manual process, such as when the developer's guide is updated. Better would be to have some tooling support that handles both develpers getting started and toolchain selection in CI. In any case swiftly can help install the chosen default toolchain. |
|
|
||
| Reliability in toolchain selection is knowing which toolchain has produced good results in the pastat a developer's desk, better would be to use one that's been verified in CI. And so, maybe the CI system uses the toolchain that's documented in the developer's guide? It can be a manual process, such as when the developer's guide is updated. Better would be to have some tooling support that handles both develpers getting started and toolchain selection in CI. In any case swiftly can help install the chosen default toolchain. | ||
|
|
||
| It is important to note it is often important to engage in certain kinds of testing that can be slower, and less reliable. The test pyramid model accommodates ths for doing integration, end-to-end testing. These should be fewer in number, and possibly less frequently. Since these tests can be less reliable and slower, sometimes they don't run with every pull request. They are commonly run on a schedule with processes in place to react to failures. |
There was a problem hiding this comment.
This bit feels off topic from the goal of the document (what toolchain should I use)
|
|
||
| It is important to note it is often important to engage in certain kinds of testing that can be slower, and less reliable. The test pyramid model accommodates ths for doing integration, end-to-end testing. These should be fewer in number, and possibly less frequently. Since these tests can be less reliable and slower, sometimes they don't run with every pull request. They are commonly run on a schedule with processes in place to react to failures. | ||
|
|
||
| In terms of toolchain selection, it can be important (depending on the project), to have integration testing with different toolchains. Sometimes this involves exploratory testing new Swift toolchain snapshots to signal readiness before the next release arrives. In other cases, a sampling of toolchain versions (often older ones) are used to build the software so that downstream projects using older toolchains can be supported. Testing is harder to achieve since the test cases themselves are not directly consumed by downstream projects, and a project might want to adopt newer test features available in newer toolchains. swiftly can also help to install these toolchains for integration testing with them. |
There was a problem hiding this comment.
Suggested change
| In terms of toolchain selection, it can be important (depending on the project), to have integration testing with different toolchains. Sometimes this involves exploratory testing new Swift toolchain snapshots to signal readiness before the next release arrives. In other cases, a sampling of toolchain versions (often older ones) are used to build the software so that downstream projects using older toolchains can be supported. Testing is harder to achieve since the test cases themselves are not directly consumed by downstream projects, and a project might want to adopt newer test features available in newer toolchains. swiftly can also help to install these toolchains for integration testing with them. | |
| In terms of toolchain selection, it can be important (depending on the project) to perform integration testing with different toolchains. Sometimes this involves testing nightly Swift toolchain snapshots to signal readiness before the next Swift release arrives. In other cases, a sampling of toolchain versions (often older ones) are used to build the software so that downstream projects using older toolchains can be supported. Testing with older toolchains is harder to achieve since the test cases themselves are not directly consumed by downstream projects, and a project might want to adopt newer test features available in recent toolchains. Swiftly can also help to install these older toolchains for integration testing with them. |
| In terms of toolchain selection, it can be important (depending on the project), to have integration testing with different toolchains. Sometimes this involves exploratory testing new Swift toolchain snapshots to signal readiness before the next release arrives. In other cases, a sampling of toolchain versions (often older ones) are used to build the software so that downstream projects using older toolchains can be supported. Testing is harder to achieve since the test cases themselves are not directly consumed by downstream projects, and a project might want to adopt newer test features available in newer toolchains. swiftly can also help to install these toolchains for integration testing with them. | ||
|
|
||
| ``` | ||
| swiftly run +6.2-snapshot make |
There was a problem hiding this comment.
What are these commands for?
|
|
||
| ## Summary | ||
|
|
||
| Depending on your workflow, there is often some kind of recommended toolchain version that can help you to succeed in the primary flow. What's needed is a standard way to record this information. The swift version file is a simple format to document the version. Tooling support, including swiftly, can help you to choose this recommended toolchain across different projects. While there are other sources of version information in Swift projects, they are designed for other things. |
There was a problem hiding this comment.
Suggested change
| Depending on your workflow, there is often some kind of recommended toolchain version that can help you to succeed in the primary flow. What's needed is a standard way to record this information. The swift version file is a simple format to document the version. Tooling support, including swiftly, can help you to choose this recommended toolchain across different projects. While there are other sources of version information in Swift projects, they are designed for other things. | |
| Depending on your workflow, there is often a recommended toolchain version that will successfully build the project. The `.swift-version` acts as a simple format to document this toolchain version. Tooling support, including swiftly, can help you to choose this recommended toolchain across different projects. While there are other sources of version information in Swift projects, they are designed for other things. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.