containertool: Rename --username/password to --default-username/password (#125)

Motivation
----------

The `--username` and `--password` options define default values which
are used if no suitable credentials can be found in `.netrc`. Their
current names could imply that they override other sources of
credentials - the help originally said this was the case (#123).
Renaming them to `--default-username` and `--default-password` reduces
the risk of misunderstanding.

Modifications
-------------

* Rename the `--user` and `--password` options to `--default-user` and
`--default-password`.
* Add checks to warn that the old versions are deprecated, and fail if
both are provided together.
* Hide the old options from `--help` and remove them from the manual
page
* Rename the environment variable versions of these options. The
environment variable change had not yet been released so deprecation
warnings are not needed.

Result
------

* New users will see more descriptive option names
* Existing users will be prompted to change the options they pass

Test Plan
---------

All existing test continue to pass.

Author: euanh

Sources/containertool/containertool.swift

@@ -40,12 +40,28 @@ enum AllowHTTP: String, ExpressibleByArgument, CaseIterable { case source, desti
     @Option(help: "Resource bundle directory")
     private var resources: [String] = []
 
-    @Option(help: "Default username, used if there are no matching entries in .netrc")
+    @Option(
+        help: ArgumentHelp(
+            "[DEPRECATED] Default username, used if there are no matching entries in .netrc. Use --default-username instead.",
+            visibility: .private
+        )
+    )
     private var username: String?
 
-    @Option(help: "Default password, used if there are no matching entries in .netrc")
+    @Option(help: "Default username, used if there are no matching entries in .netrc")
+    private var defaultUsername: String?
+
+    @Option(
+        help: ArgumentHelp(
+            "[DEPRECATED] Default password, used if there are no matching entries in .netrc.   Use --default-password instead.",
+            visibility: .private
+        )
+    )
     private var password: String?
 
+    @Option(help: "Default password, used if there are no matching entries in .netrc")
+    private var defaultPassword: String?
+
     @Flag(name: .shortAndLong, help: "Verbose output")
     private var verbose: Bool = false
 
@@ -70,13 +86,37 @@ enum AllowHTTP: String, ExpressibleByArgument, CaseIterable { case source, desti
     @Option(help: "Specify the netrc file path")
     private var netrcFile: String?
 
+    mutating func validate() throws {
+        if username != nil {
+            guard defaultUsername == nil else {
+                throw ValidationError(
+                    "--default-username and --username cannot be specified together.   Please use --default-username only."
+                )
+            }
+
+            log("Deprecation warning: --username is deprecated, please use --default-username instead.")
+            defaultUsername = username
+        }
+
+        if password != nil {
+            guard defaultPassword == nil else {
+                throw ValidationError(
+                    "--default-password and --password cannot be specified together.   Please use --default-password only."
+                )
+            }
+
+            log("Deprecation warning: --password is deprecated, please use --default-password instead.")
+            defaultPassword = password
+        }
+    }
+
     func run() async throws {
         // MARK: Apply defaults for unspecified configuration flags
 
         let env = ProcessInfo.processInfo.environment
         let defaultRegistry = defaultRegistry ?? env["CONTAINERTOOL_DEFAULT_REGISTRY"] ?? "docker.io"
-        let username = username ?? env["CONTAINERTOOL_USERNAME"]
-        let password = password ?? env["CONTAINERTOOL_PASSWORD"]
+        let username = defaultUsername ?? env["CONTAINERTOOL_DEFAULT_USERNAME"]
+        let password = defaultPassword ?? env["CONTAINERTOOL_DEFAULT_PASSWORD"]
         let from = from ?? env["CONTAINERTOOL_BASE_IMAGE"] ?? "swift:slim"
         let os = os ?? env["CONTAINERTOOL_OS"] ?? "linux"
 

Sources/swift-container-plugin/Documentation.docc/build-container-image.md

@@ -33,13 +33,13 @@ Wrap a binary in a container image and publish it.
 
   If the `product` being packaged has a [resource bundle](https://developer.apple.com/documentation/xcode/bundling-resources-with-a-swift-package) it will be added to the image automatically.
 
-- term  `--username <username>`:
+- term  `--default-username <username>`:
   Default username to use when logging into the registry.
 
   This username is used if there is no matching `.netrc` entry for the registry, there is no `.netrc` file, or the `--disable-netrc` option is set.
   The same username is used for the source and destination registries.
 
-- term  `--password <password>`:
+- term  `--default-password <password>`:
   Default password to use when logging into the registry.
 
   This password is used if there is no matching `.netrc` entry for the registry, there is no `.netrc` file, or the `--disable-netrc` option is set.