Merge pull request #2539 from dempseyatgithub/0441-update-to-deprecate-not-obsolete

Accept SE-0441 and revise to reflect changes in accepted proposal

Author: rjmccall

proposals/0441-formalize-language-mode-terminology.md

@@ -3,15 +3,15 @@
 * Proposal: [SE-0441](0441-formalize-language-mode-terminology.md)
 * Author: [James Dempsey](https://github.com/dempseyatgithub)
 * Review Manager: [John McCall](https://github.com/rjmccall)
-* Status: **Active review (July 15th...29th, 2024)**
-* Implementation: [apple/swift-package-manager#7620](https://github.com/apple/swift-package-manager/pull/7620)
-* Review: ([first pitch](https://forums.swift.org/t/pitch-formalize-swift-language-mode-naming-in-tools-and-api/71733)) ([second pitch](https://forums.swift.org/t/pitch-2-formalize-language-mode-naming-in-tools-and-api/72136)) ([review](https://forums.swift.org/t/se-0441-formalize-language-mode-terminology/73182))
+* Status: **Accepted** 
+* Implementation: [swiftlang/swift-package-manager#7620](https://github.com/swiftlang/swift-package-manager/pull/7620), [swiftlang/swift#75564](https://github.com/swiftlang/swift/pull/75564)
+* Review: ([first pitch](https://forums.swift.org/t/pitch-formalize-swift-language-mode-naming-in-tools-and-api/71733)) ([second pitch](https://forums.swift.org/t/pitch-2-formalize-language-mode-naming-in-tools-and-api/72136)) ([review](https://forums.swift.org/t/se-0441-formalize-language-mode-terminology/73182)) ([acceptance](https://forums.swift.org/t/accepted-se-0441-formalize-language-mode-terminology/73716))
 
 ## Introduction
 The term "Swift version” can refer to either the toolchain/compiler version or the language mode. This ambiguity is a consistent source of confusion. This proposal formalizes the term _language mode_ in tool options and APIs.
 
 ## Proposed Solution
-The proposed solution is to use the term _language mode_ for the appropriate Swift compiler option and Swift Package Manager APIs. Use of "Swift version" to refer to language mode will be deprecated or obsoleted as needed.
+The proposed solution is to use the term _language mode_ for the appropriate Swift compiler option and Swift Package Manager APIs. Use of "Swift version" to refer to language mode will be deprecated.
 
 ### Terminology
 The term _language mode_ has been consistently used to describe this compiler feature since it was introduced with Swift 4.0 and is an established term of art in the Swift community.
@@ -49,7 +49,7 @@ Add a new `init` method to `Package` with the following changes from the current
 - The parameter `swiftLanguageVersions` is renamed to `swiftLanguageModes`
 - The parameter type is now an optional array of `SwiftLanguageMode` values instead of `SwiftVersion` values
 
-The existing init method will be marked as `obsoleted` and `renamed` allowing the compiler to provide a fix-it.
+The existing init method will be marked as `deprecated` and `renamed` allowing the compiler to provide a fix-it.
 
 #### 2. Rename `swiftLanguageVersions` property to `swiftLanguageModes`
 Rename the public `Package` property `swiftLanguageVersions` to `swiftLanguageModes`. Add a `swiftLanguageVersions` computed property that accesses `swiftLanguageModes` for backwards compatibility. 
@@ -104,7 +104,7 @@ The `-swift-version` option will be suppressed from the top-level help of the co
 ### Swift Package Manager
 Proposed Swift Package Manager API changes are limited to manifests \>= 6.0:
 
-### New Package init method and obsoleted init method
+### New Package init method and deprecated init method
 A new `init` method will be added to `Package` that renames the `swiftLanguageVersions` parameter to `swiftLanguageModes` with the type of the parameter being an optional array of `SwiftLanguageMode` values instead of `SwiftVersion` values:
 
 ```swift
@@ -123,10 +123,11 @@ Package(
 ```
 
 
-The existing init method will be marked as `obsoleted` and `renamed`, allowing the compiler to provide a fix-it:
+The existing init method will be marked as `deprecated` and `renamed`, allowing the compiler to provide a fix-it:
 
 ```
-@available(_PackageDescription, introduced: 5.3, obsoleted: 6, renamed:
+@_disfavoredOverload
+@available(_PackageDescription, introduced: 5.3, deprecated: 6, renamed:
 "init(name:defaultLocalization:platforms:pkgConfig:providers:products:
 dependencies:targets:swiftLanguageModes:cLanguageStandard:
 cxxLanguageStandard:)")
@@ -139,19 +140,6 @@ cxxLanguageStandard:)")
 	) {
 ```
 
-#### Obsoleting existing init method
-The existing method must be obsoleted because the two methods are ambiguous when the default value for `swiftLanguageVersions` / `swiftLanguageModes` is used:
-
-```
-Package (  // Error: Ambiguous use of 'init'
-  name: "MyPackage",
-  products: ...,
-  targets: ...
-)
-```
-
-This follows the same approach used by all past revisions of the Package `init` method.
-
 See the **Source compatibility** section for more details about this change.
 
 ### Rename `swiftLanguageVersions` property to `swiftLanguageModes`
@@ -212,11 +200,11 @@ public struct SwiftSetting {
 ```
 
 ## Source compatibility
-The new Package `init` method and obsoleting of the existing `init` method will cause source breakage for package manifests that specify the existing `swiftLanguageVersions` parameter when updating to swift tools version 6.0
+The new Package `init` method and deprecating the existing `init` method will cause a deprecation warning for package manifests that specify the existing `swiftLanguageVersions` parameter when updating to swift tools version 6.0
 
 A search of manifest files in public repositories suggests that about 10% of manifest files will encounter this breakage.
 
-Because the obsoleted `init` method is annotated as `renamed` the compiler will automatically provide a fix-it to update to the new `init` method.
+Because the deprecated `init` method is annotated as `renamed` the compiler will automatically provide a fix-it to update to the new `init` method.
 
 Renaming the public `swiftLanguageVersions` property of `Package` preserves backwards compatibility by introducing a computed property with that name. The computed property will be marked as `deprecated` in 6.0 and annotated as `renamed` to provide a fix-it.