Prepare for 1.0 release (#355)

CHANGELOG.md

@@ -4,18 +4,30 @@
 Add new items at the end of the relevant section under **Unreleased**.
 -->
 
-This project follows semantic versioning. While still in major version `0`,
-source-stability is only guaranteed within minor versions (e.g. between
-`0.0.3` and `0.0.4`). If you want to guard against potentially source-breaking
-package updates, you can specify your package dependency using
-`.upToNextMinor(from: "0.5.0")` as the requirement.
-
 ## [Unreleased]
 
 *No changes yet.*
 
 ---
 
+## [1.0.0] - 2021-09-10
+
+The 1.0 release marks an important milestone —
+`ArgumentParser` is now source stable!
+
+### Changes
+
+- `ArgumentParser` now provides a DocC documentation catalog, so you
+  can view rendered articles and symbol documentation directly within
+  Xcode.
+
+### Fixes
+
+- Parsing works as expected for options with single-dash names that
+  are declared using the `.upToNextOption` parsing strategy.
+
+---
+
 ## [0.5.0] - 2021-09-02
 
 ### Additions
@@ -515,7 +527,8 @@ This changelog's format is based on [Keep a Changelog](https://keepachangelog.co
 
 <!-- Link references for releases -->
 
-[Unreleased]: https://github.com/apple/swift-argument-parser/compare/0.5.0...HEAD
+[Unreleased]: https://github.com/apple/swift-argument-parser/compare/1.0.0...HEAD
+[1.0.0]: https://github.com/apple/swift-argument-parser/compare/0.5.0...1.0.0
 [0.5.0]: https://github.com/apple/swift-argument-parser/compare/0.4.4...0.5.0
 [0.4.4]: https://github.com/apple/swift-argument-parser/compare/0.4.3...0.4.4
 [0.4.3]: https://github.com/apple/swift-argument-parser/compare/0.4.2...0.4.3

Package@swift-5.5.swift

@@ -12,7 +12,7 @@
 
 import PackageDescription
 
-var package = Package(
+let package = Package(
     name: "swift-argument-parser",
     products: [
         .library(
@@ -60,17 +60,12 @@ var package = Package(
             name: "ArgumentParserUnitTests",
             dependencies: ["ArgumentParser", "ArgumentParserTestHelpers"],
             exclude: ["CMakeLists.txt"]),
+        .testTarget(
+            name: "ArgumentParserPackageManagerTests",
+            dependencies: ["ArgumentParser", "ArgumentParserTestHelpers"],
+            exclude: ["CMakeLists.txt"]),
         .testTarget(
             name: "ArgumentParserExampleTests",
             dependencies: ["ArgumentParserTestHelpers"]),
     ]
 )
-
-#if swift(>=5.2)
-// Skip if < 5.2 to avoid issue with nested type synthesized 'CodingKeys'
-package.targets.append(
-    .testTarget(
-        name: "ArgumentParserPackageManagerTests",
-        dependencies: ["ArgumentParser", "ArgumentParserTestHelpers"],
-        exclude: ["CMakeLists.txt"]))
-#endif

README.md

@@ -5,12 +5,13 @@
 Begin by declaring a type that defines the information
 that you need to collect from the command line.
 Decorate each stored property with one of `ArgumentParser`'s property wrappers,
-declare conformance to `ParsableCommand`,
-and implement your command's logic in the `run()` method.
+and then declare conformance to `ParsableCommand` and add the `@main` attribute.
+Finally, implement your command's logic in the `run()` method.
 
 ```swift
 import ArgumentParser
 
+@main
 struct Repeat: ParsableCommand {
     @Flag(help: "Include a counter with each repetition.")
     var includeCounter = false
@@ -33,11 +34,8 @@ struct Repeat: ParsableCommand {
         }
     }
 }
-
-Repeat.main()
 ```
 
-You kick off execution by calling your type's static `main()` method.
 The `ArgumentParser` library parses the command-line arguments,
 instantiates your command type, and then either executes your `run()` method
 or exits with a useful message.
@@ -53,6 +51,7 @@ hello
 hello
 $ repeat --count 3
 Error: Missing expected argument 'phrase'.
+Help:  <phrase>  The phrase to repeat.
 Usage: repeat [--count <count>] [--include-counter] <phrase>
   See 'repeat --help' for more information.
 $ repeat --help
@@ -67,7 +66,8 @@ OPTIONS:
   -h, --help              Show help for this command.
 ```
 
-For more information and documentation about all supported options, see [the `Documentation` folder at the root of the repository](https://github.com/apple/swift-argument-parser/tree/main/Documentation).
+For more information and documentation about all supported options, 
+see the library's documentation in Xcode.
 
 ## Examples
 
@@ -82,35 +82,40 @@ You can also see examples of `ArgumentParser` adoption among Swift project tools
 - [`indexstore-db`](https://github.com/apple/indexstore-db/pull/72) is a simple utility with two commands.
 - [`swift-format`](https://github.com/apple/swift-format/pull/154) uses some advanced features, like custom option values and hidden flags.
 
-## Adding `ArgumentParser` as a Dependency
+## Project Status
 
-To use the `ArgumentParser` library in a SwiftPM project, 
-add the following line to the dependencies in your `Package.swift` file:
+The Swift Argument Parser package is source stable;
+version numbers follow semantic versioning.
+Source breaking changes to public API can only land in a new major version.
 
-```swift
-.package(url: "https://github.com/apple/swift-argument-parser", from: "0.5.0"),
-```
+The public API of version 1.0 of the `swift-argument-parser` package
+consists of non-underscored declarations that are marked public in the `ArgumentParser` module.
+Interfaces that aren't part of the public API may continue to change in any release,
+including the exact wording and formatting of the autogenerated help and error messages,
+as well as the package’s examples, tests, utilities, and documentation. 
 
-Because `ArgumentParser` is under active development,
-source-stability is only guaranteed within minor versions (e.g. between `0.0.3` and `0.0.4`).
-If you don't want potentially source-breaking package updates,
-use this dependency specification instead:
+Future minor versions of the package may introduce changes to these rules as needed.
 
-```swift
-.package(url: "https://github.com/apple/swift-argument-parser", .upToNextMinor(from: "0.5.0")),
-```
+We'd like this package to quickly embrace Swift language and toolchain improvements that are relevant to its mandate.
+Accordingly, from time to time,
+we expect that new versions of this package will require clients to upgrade to a more recent Swift toolchain release.
+Requiring a new Swift release will only require a minor version bump.
 
-Finally, include `"ArgumentParser"` as a dependency for your executable target:
+## Adding `ArgumentParser` as a Dependency
+
+To use the `ArgumentParser` library in a SwiftPM project, 
+add it to the dependencies for your package and your command-line executable target:
 
 ```swift
 let package = Package(
     // name, platforms, products, etc.
     dependencies: [
-        .package(url: "https://github.com/apple/swift-argument-parser", from: "0.4.0"),
         // other dependencies
+        .package(url: "https://github.com/apple/swift-argument-parser", from: "1.0.0"),
     ],
     targets: [
-        .target(name: "<command-line-tool>", dependencies: [
+        .executableTarget(name: "<command-line-tool>", dependencies: [
+            // other dependencies
             .product(name: "ArgumentParser", package: "swift-argument-parser"),
         ]),
         // other targets

Sources/ArgumentParser/Documentation.docc/Extensions/Flag.md

@@ -15,7 +15,7 @@
 
 ### Counted Flags
 
-- ``init(name:help:)-87c7k``
+- ``init(name:help:)``
 
 ### Custom Enumerable Flags
 
@@ -37,7 +37,3 @@
 ### Deprecated APIs
 
 - ``init()``
-- ``init(name:default:exclusivity:help:)``
-- ``init(name:help:)-5iirr``
-- ``init(name:exclusivity:help:)``
-- ``init(name:exclusivity:help:)``