From 3477d46736ddc80ca9774f7b1a06a6d48f6c15d1 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Wed, 24 Sep 2025 08:20:22 -0700 Subject: [PATCH 1/2] using more direct language to make it clear Package.resolved doesn't pin versions for dependencies --- .../ResolvingPackageVersions.md | 22 +++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/Sources/PackageManagerDocs/Documentation.docc/ResolvingPackageVersions.md b/Sources/PackageManagerDocs/Documentation.docc/ResolvingPackageVersions.md index c1053f082d3..2db283ce394 100644 --- a/Sources/PackageManagerDocs/Documentation.docc/ResolvingPackageVersions.md +++ b/Sources/PackageManagerDocs/Documentation.docc/ResolvingPackageVersions.md @@ -5,8 +5,9 @@ Coordinate and constrain dependencies for your package. ## Overview The package manager records the result of dependency resolution in a file named `Package.resolved` at the top-level of the package. -When this file is already present and you are directly resolving dependencies, `Package.resolved` is used to define the versions of the dependencies rather than the package manager finding the latest eligible versions. -If the package is being resolved as a dependency from another package, any local `Package.resolved` file is ignored during that resolution. +When this file is present and you are resolving dependencies for the top-level (leaf) package of a dependency tree, the package manager uses the `Package.resolved` file as a cache of versions of the dependencies. +The Package.resolved file does not pin dependency versions for packages used as libraries, or are otherwise included as a dependency for another Swift project. +If the package is being resolved as a dependency from another package, its own `Package.resolved` file is ignored during that resolution. Most SwiftPM commands implicitly invoke dependency resolution before running, and cancel with an error if dependencies cannot be resolved. @@ -15,19 +16,22 @@ Most SwiftPM commands implicitly invoke dependency resolution before running, an Run to resolve the dependencies, taking into account the current version constraints in the `Package.swift` manifest and a `Package.resolved` resolved versions file. For packages with a `Package.resolved` file, the `resolve` command resolves to those versions as long as they are still eligible. -If the resolved version's file changes (for example, because a teammate shared an update through source control) the next `resolve` command attempts to update the package dependencies to match that file. -In most cases the resolve command performs no changes unless the `Package.swift` manifest or `Package.resolved` file changed. +If the resolved version's file changes (for example, because a teammate shared an update through source control), the next `resolve` command attempts to update the package dependencies to match that file. +In most cases, the resolve command performs no changes unless the `Package.swift` manifest or `Package.resolved` file has changed. ### Updating the dependencies -Running updates all dependencies to the latest eligible versions and updates the `Package.resolved` file accordingly. +Run to update a package's dependencies to the latest eligible versions, which also updates the package's local cache of resolved versions in the `Package.resolved` file. ### Coordinating versions of dependencies for your package -Keep the `Package.resolved` file in source control to coordinate specific dependencies for direct consumers of the package. -If a `Package.resolved` doesn't exist, each user separately resolves dependency versions, only updating when they run , and new users start with the latest eligible version of each dependency. -If the `Package.resolved` file does exist, any command that requires dependencies (for example, or ) attempts to resolve the versions of dependencies recorded in the file. +You can use `Package.resolved` to coordinate the versions of dependencies it uses for a leaf Swift project - one that isn't being used as a dependency. +For example, you can keep a `Package.resolved` file in source control, or resolve it locally and pass it to a container image build process, in order to ensure another build uses the same versions of dependencies. -The `Package.resolved` doesn't constrain upstream dependencies of the package. +The `Package.resolved` only acts as a cache for leaf projects. +It does not provide any dependency pinning for libraries or packages that are used as dependencies for other Swift projects. For example, if your package presents a library and has `Package.resolved` checked in, those versions are ignored by the package that depends on your library, and the latest eligible versions are chosen. For more information on constraining dependency versions, see . + +If a `Package.resolved` doesn't exist, each user or build system separately resolves dependency versions, only updating when they run , and new users start with the latest eligible version of each dependency. +If the `Package.resolved` file does exist, any command that requires dependencies (for example, or ) attempts to resolve the versions of dependencies recorded in the file. From 68959650357a92b6b2adbb9657e3d851d390afc1 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Mon, 29 Sep 2025 14:36:03 +0100 Subject: [PATCH 2/2] added example using --force-resolved-versions and removed references to Package.resolved as a versions cache --- .../Documentation.docc/ResolvingPackageVersions.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/Sources/PackageManagerDocs/Documentation.docc/ResolvingPackageVersions.md b/Sources/PackageManagerDocs/Documentation.docc/ResolvingPackageVersions.md index 2db283ce394..33f46108f2b 100644 --- a/Sources/PackageManagerDocs/Documentation.docc/ResolvingPackageVersions.md +++ b/Sources/PackageManagerDocs/Documentation.docc/ResolvingPackageVersions.md @@ -15,20 +15,26 @@ Most SwiftPM commands implicitly invoke dependency resolution before running, an Run to resolve the dependencies, taking into account the current version constraints in the `Package.swift` manifest and a `Package.resolved` resolved versions file. For packages with a `Package.resolved` file, the `resolve` command resolves to those versions as long as they are still eligible. +If you want to explicitly use the dependencies written into `Package.resolved`, use the `--force-resolved-versions` when invoking `swift resolve`. +For example, to force the dependencies to align with the versions defined in `Package.resolved`, use: + +```bash +swift package resolve --force-resolved-versions +``` If the resolved version's file changes (for example, because a teammate shared an update through source control), the next `resolve` command attempts to update the package dependencies to match that file. In most cases, the resolve command performs no changes unless the `Package.swift` manifest or `Package.resolved` file has changed. ### Updating the dependencies -Run to update a package's dependencies to the latest eligible versions, which also updates the package's local cache of resolved versions in the `Package.resolved` file. +Run to update a package's dependencies to the latest eligible versions, which also updates the `Package.resolved` file. ### Coordinating versions of dependencies for your package You can use `Package.resolved` to coordinate the versions of dependencies it uses for a leaf Swift project - one that isn't being used as a dependency. For example, you can keep a `Package.resolved` file in source control, or resolve it locally and pass it to a container image build process, in order to ensure another build uses the same versions of dependencies. -The `Package.resolved` only acts as a cache for leaf projects. +The `Package.resolved` only helps to resolve dependencies to the specific versions it defines for leaf projects. It does not provide any dependency pinning for libraries or packages that are used as dependencies for other Swift projects. For example, if your package presents a library and has `Package.resolved` checked in, those versions are ignored by the package that depends on your library, and the latest eligible versions are chosen. For more information on constraining dependency versions, see .