Skip to content

Clarify documented behavior of versioned manifest files in usage docs #8462

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 8, 2025
Merged

Clarify documented behavior of versioned manifest files in usage docs #8462

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 17 additions & 9 deletions Documentation/Usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -497,7 +497,7 @@ This feature is intended for use in the following scenarios:

It is *not* expected that the packages would ever use this feature unless absolutely
necessary to support existing clients. Specifically, packages *should not*
adopt this syntax for tagging versions supporting the _latest GM_ Swift
adopt this syntax for tagging versions supporting the _latest released_ Swift
version.

The package manager supports looking for any of the following marked tags, in
Expand All @@ -511,7 +511,7 @@ order of preference:

The package manager will additionally look for a version-specific marked
manifest version when loading the particular version of a package, by searching
for a manifest in the form of `Package@swift-3.swift`. The set of markers
for a manifest in the form of `Package@swift-6.swift`. The set of markers
looked for is the same as for version-specific tag selection.

This feature is intended for use in cases where a package wishes to maintain
Expand All @@ -521,20 +521,28 @@ changes in the manifest API).

It is *not* expected the packages would ever use this feature unless absolutely
necessary to support existing clients. Specifically, packages *should not*
adopt this syntax for tagging versions supporting the _latest GM_ Swift
adopt this syntax for tagging versions supporting the _latest released_ Swift
version.

In case the current Swift version doesn't match any version-specific manifest,
the package manager will pick the manifest with the most compatible tools
version. For example, if there are three manifests:

`Package.swift` (tools version 3.0)
`Package@swift-4.swift` (tools version 4.0)
`Package@swift-4.2.swift` (tools version 4.2)
- `Package.swift` (tools version 6.0)
- `Package@swift-5.10.swift` (tools version 5.10)
- `Package@swift-5.9.swift` (tools version 5.9)

The package manager will pick `Package.swift` on Swift 3, `[email protected]` on
Swift 4, and `[email protected]` on Swift 4.2 and above because its tools
version will be most compatible with future version of the package manager.
The package manager will pick `Package.swift` on Swift 6 and above, because its
tools version will be most compatible with future version of the package manager.
When using Swift 5.10, it will pick `[email protected]`. Otherwise, when
using Swift 5.9 it will pick `[email protected]`, and this is the minimum
tools version this package may be used with.

A package may have versioned manifest files which specify newer tools versions
than its unversioned `Package.swift` file[^1]. In this scenario, the manifest
corresponding to the newest-compatible tools version will be used.

[^1]: Support for having a versioned manifest file with a _newer_ tools version was required when the feature was first introduced, because prior versions of the package manager were not aware of the concept and only knew to look for the unversioned `Package.swift`. This is still supported, but there have been many Swift releases since the feature was introduced and it is now considered best practice to have `Package.swift` declare the newest-supported tools version and for versioned manifest files to only specifer older versions.

## Editing a Package

Expand Down