re-introduce Package.Dependency.Requirement::upToNextMajor and ::upToNextMinor (#3922)

motivation: preserve source compatibility

changes:
* re-introduce Package.Dependency.Requirement::upToNextMajor and ::upToNextMinor
* mark  Package.Dependency.Requirement::upToNextMajor and ::upToNextMinor as @_disfavoredOverload to disambiguate from the extension on Range
* add relevant API docs
* fix a few typos in docs

rdar://86041332

Author: tomerd

CHANGELOG.md

@@ -16,7 +16,7 @@ Swift 5.6
 
 * [#3641]
 
-  Soft deprecate `.package(name:, url:)` dependency syntax in favour of `.package(url:)`, given that an explicit `name` attribute is no longer needed for target depedendencies lookup.
+  Soft deprecate `.package(name:, url:)` dependency syntax in favor of `.package(url:)`, given that an explicit `name` attribute is no longer needed for target dependencies lookup.
 
 * [#3641]
 
@@ -38,11 +38,11 @@ Swift 5.5
 
 * [#3280]
 
-  A more intuitive `.product(name:, package:)` target depedendency syntax is now accepted, where `package` is the package identifier as defined by the package URL.
+  A more intuitive `.product(name:, package:)` target dependency syntax is now accepted, where `package` is the package identifier as defined by the package URL.
 
 * [#3316]
 
-  Test targets can now link against executable targets as if they were libraries, so that they can test any data strutures or algorithms in them.  All the code in the executable except for the main entry point itself is available to the unit test.  Separate executables are still linked, and can be tested as a subprocess in the same way as before.  This feature is available to tests defined in packages that have a tools version of `5.5` or newer. 
+  Test targets can now link against executable targets as if they were libraries, so that they can test any data structures or algorithms in them.  All the code in the executable except for the main entry point itself is available to the unit test.  Separate executables are still linked, and can be tested as a subprocess in the same way as before.  This feature is available to tests defined in packages that have a tools version of `5.5` or newer. 
 
 Swift 5.4
 -----------
@@ -54,7 +54,7 @@ Swift 5.4
 
     [SR-13566] The Swift tools version specification in each manifest file now accepts any combination of _horizontal_ whitespace characters surrounding `swift-tools-version`, if and only if the specified version ≥ `5.4`. For example, `//swift-tools-version:	5.4` and `//		 swift-tools-version: 5.4` are valid.
 
-    All [Unicode line terminators](https://www.unicode.org/reports/tr14/) are now recognised in `Package` manifests. This ensures correctness in parsing manifests that are edited and/or built on many non-Unix-like platforms that use ASCII or Unicode encodings. 
+    All [Unicode line terminators](https://www.unicode.org/reports/tr14/) are now recognized in `Package` manifests. This ensures correctness in parsing manifests that are edited and/or built on many non-Unix-like platforms that use ASCII or Unicode encodings. 
 
   * API Removal
 

Sources/PackageDescription/PackageDependency.swift

@@ -352,7 +352,17 @@ extension Package.Dependency {
     /// The following example allows the Swift Package Manager to pick
     /// versions 1.2.3, 1.2.4, 1.2.5, as well as 1.2.6.
     ///
-    ///     .package(url: "https://example.com/example-package.git", "1.2.3"..."1.2.6"),
+    ///    .package(url: "https://example.com/example-package.git", "1.2.3"..."1.2.6"),
+    ///
+    /// The following example allows the Swift Package Manager to pick
+    /// versions between 1.0.0 and 2.0.0
+    ///
+    ///    .package(url: "https://example.com/example-package.git", .upToNextMajor("1.0.0"),
+    ///
+    /// The following example allows the Swift Package Manager to pick
+    /// versions between 1.0.0 and 1.1.0
+    ///
+    ///    .package(url: "https://example.com/example-package.git", .upToNextMinor("1.0.0"),
     ///
     /// - Parameters:
     ///     - name: The name of the package, or `nil` to deduce it from the URL.
@@ -367,6 +377,18 @@ extension Package.Dependency {
         return .package(name: name, url: url, closedRange: range)
     }
 
+    /// Adds a package dependency starting with a specific minimum version, going
+    /// up to and including a specific maximum version.
+    ///
+    /// The following example allows the Swift Package Manager to pick
+    /// versions 1.2.3, 1.2.4, 1.2.5, as well as 1.2.6.
+    ///
+    ///    .package(url: "https://example.com/example-package.git", "1.2.3"..."1.2.6"),
+    ///
+    /// - Parameters:
+    ///     - name: The name of the package, or `nil` to deduce it from the URL.
+    ///     - url: The valid Git URL of the package.
+    ///     - range: The closed version range requirement.
     private static func package(
         name: String?,
         url: String,
@@ -504,7 +526,17 @@ extension Package.Dependency {
     /// The following example allows the Swift Package Manager to pick
     /// versions `1.2.3`, `1.2.4`, `1.2.5`, but not `1.2.6`.
     ///
-    ///     .package(id: "scope.name", "1.2.3"..<"1.2.6"),
+    ///    .package(id: "scope.name", "1.2.3"..<"1.2.6"),
+    ///
+    /// The following example allows the Swift Package Manager to pick
+    /// versions between 1.0.0 and 2.0.0
+    ///
+    ///    .package(id: "scope.name", .upToNextMajor("1.0.0"),
+    ///
+    /// The following example allows the Swift Package Manager to pick
+    /// versions between 1.0.0 and 1.1.0
+    ///
+    ///    .package(id: "scope.name", .upToNextMinor("1.0.0"),
     ///
     /// - Parameters:
     ///     - id: The identity of the package.
@@ -523,7 +555,7 @@ extension Package.Dependency {
     /// The following example allows the Swift Package Manager to pick
     /// versions 1.2.3, 1.2.4, 1.2.5, as well as 1.2.6.
     ///
-    ///     .package(id: "scope.name", "1.2.3"..."1.2.6"),
+    ///    .package(id: "scope.name", "1.2.3"..."1.2.6"),
     ///
     /// - Parameters:
     ///     - id: The identity of the package.

Sources/PackageDescription/PackageRequirement.swift

@@ -183,10 +183,6 @@ extension Package.Dependency {
 extension Package.Dependency {
     /// An enum that represents the requirement for a package dependency.
     ///
-    /// The dependency requirement can be defined as one of three different version requirements:
-    ///
-    /// **A version-based requirement.**
-    ///
     /// Decide whether your project accepts updates to a package dependency up
     /// to the next major version or up to the next minor version. To be more
     /// restrictive, select a specific version range or an exact version.
@@ -195,34 +191,6 @@ extension Package.Dependency {
     /// The version rule requires Swift packages to conform to semantic
     /// versioning. To learn more about the semantic versioning standard,
     /// visit [semver.org](https://semver.org).
-    ///
-    /// Selecting the version requirement is the recommended way to add a package dependency. It allows you to create a balance between restricting changes and obtaining improvements and features.
-    ///
-    /// **A branch-based requirement**
-    ///
-    /// Select the name of the branch for your package dependency to follow.
-    /// Use branch-based dependencies when you're developing multiple packages
-    /// in tandem or when you don't want to publish versions of your package dependencies.
-    ///
-    /// Note that packages which use branch-based dependency requirements
-    /// can't be added as dependencies to packages that use version-based dependency
-    /// requirements; you should remove branch-based dependency requirements
-    /// before publishing a version of your package.
-    ///
-    /// **A commit-based requirement**
-    ///
-    /// Select the commit hash for your package dependency to follow.
-    /// Choosing this option isn't recommended, and should be limited to
-    /// exceptional cases. While pinning your package dependency to a specific
-    /// commit ensures that the package dependency doesn't change and your
-    /// code remains stable, you don't receive any updates at all. If you worry about
-    /// the stability of a remote package, consider one of the more
-    /// restrictive options of the version-based requirement.
-    ///
-    /// Note that packages which use commit-based dependency requirements
-    /// can't be added as dependencies to packages that use version-based
-    /// dependency requirements; you should remove commit-based dependency
-    /// requirements before publishing a version of your package.
     @available(_PackageDescription, introduced: 999)
     public enum RegistryRequirement {
         case exact(Version)
@@ -250,3 +218,15 @@ extension Range {
         return version ..< Version(version.major, version.minor + 1, 0)
     }
 }
+
+@available(_PackageDescription, deprecated: 5.6)
+extension Package.Dependency.Requirement {
+    @_disfavoredOverload
+    public static func upToNextMajor(from version: Version) -> Self {
+        return .rangeItem(.upToNextMajor(from: version))
+    }
+    @_disfavoredOverload
+    public static func upToNextMinor(from version: Version) -> Self {
+        return .rangeItem(.upToNextMinor(from: version))
+    }
+}