Update README and other documentation files (#466)

This updates several project documentation files, including `README`,
`CONTRIBUTING`, and DocC articles, to better describe the package and
explain how to use it with recently updated tools.

### Checklist:

- [x] Code and documentation should follow the style of the [Style
Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md).
- [x] If public symbols are renamed or modified, DocC references should
be updated.

Resolves rdar://129024698

Author: stmontgomery

CONTRIBUTING.md

@@ -1,11 +1,11 @@
-# Contributing to `swift-testing`
+# Contributing to Swift Testing
 
 There are many ways to contribute to this project. If you are making changes
-that do not materially affect the user-facing semantics of `swift-testing`, such
+that don't materially affect the user-facing semantics of Swift Testing, such
 as fixing bugs or writing documentation, feel free to open a pull request (PR)
 directly.
 
-Larger changes that _do_ materially change the semantics of `swift-testing`,
+Larger changes that _do_ materially change the semantics of Swift Testing,
 such as new APIs or modifications to existing APIs, must undergo community
 discussion prior to being accepted.
 
@@ -33,17 +33,17 @@ hosting service.
 
 ## Setting up the development environment
 
-First, clone the `swift-testing` repository from
+First, clone the Swift Testing repository from
 [https://github.com/apple/swift-testing](https://github.com/apple/swift-testing).
 
-If you are preparing to make a contribution, you should fork the repository first
+If you're preparing to make a contribution, you should fork the repository first
 and clone the fork which will make opening PRs easier.
 
 ### Using Xcode (easiest)
 
-1. Install the latest beta or release Xcode from
-   [https://developer.apple.com/xcode](https://developer.apple.com/xcode).
-1. Open the `Package.swift` file from the cloned `swift-testing` repository in
+1. Install the latest beta version of
+   [Xcode](https://developer.apple.com/xcode).
+1. Open the `Package.swift` file from the cloned Swift Testing repository in
    Xcode.
 1. Select the `swift-testing-Package` scheme (if not already selected) and the
    "My Mac" run destination.
@@ -54,18 +54,18 @@ and clone the fork which will make opening PRs easier.
 If you are using macOS and have Xcode installed, you can use Swift from the
 command line immediately.
 
-If you are not using macOS or do not have Xcode installed, you need to download
+If you aren't using macOS or do not have Xcode installed, you need to download
 and install a toolchain.
 
 #### Installing a toolchain
 
-1. Download a toolchain. A recent **trunk development snapshot** toolchain is
+1. Download a toolchain. A recent **6.0 development snapshot** toolchain is
    required to build the testing library. Visit
-   [swift.org](https://www.swift.org/download/#trunk-development-main) and
-   download the most recent toolchain from the section titled
-   **Snapshots — Trunk Development (main)**.
+   [swift.org](http://swift.org/install) and download the most recent toolchain
+   from the section titled **release/6.0** under **Development Snapshots** on
+   the page for your platform.
 
-   Be aware that development snapshot toolchains are not intended for day-to-day
+   Be aware that development snapshot toolchains aren't intended for day-to-day
    development and may contain defects that affect the programs built with them.
 1. Install the toolchain and confirm it can be located successfully:
 
@@ -87,7 +87,7 @@ and install a toolchain.
 
 ## Local development
 
-With a Swift toolchain installed and the `swift-testing` repository cloned, you
+With a Swift toolchain installed and the Swift Testing repository cloned, you
 are ready to make changes and test them locally.
 
 ### Building
@@ -103,7 +103,7 @@ $> swift test
 ```
 
 <!-- FIXME: Uncomment this once the the `swift test` command support running
-  specific `swift-testing` tests.
+  specific Swift Testing tests.
 
 To learn how to run only specific tests or other testing options, run `swift
 test --help` to view the usage documentation.
@@ -166,7 +166,7 @@ your contributions are licensed under the
 
 ## Continuous integration
 
-`swift-testing` uses the [`swift-ci`](https://ci.swift.org/) infrastructure for
+Swift Testing uses the [`swift-ci`](https://ci.swift.org/) infrastructure for
 its continuous integration (CI) testing. The bots can be triggered on PRs if you
 have commit access. Otherwise, ask one of the code owners to trigger them for
 you.

Documentation/CMake.md

@@ -1,8 +1,9 @@
 # Building with CMake
 
-## Add `swift-testing` to Your Project
+## Add Swift Testing to your project
 
-Add `swift-testing` with to your project using the standard `FetchContent` or `find_package` mechanism, as appropriate for your project. For example:
+Add Swift Testing to your project using the standard `FetchContent` or
+`find_package` mechanism, as appropriate for your project. For example:
 
 ```cmake
 include(FetchContent)
@@ -12,11 +13,12 @@ FetchContent_Declare(SwiftTesting
 FetchContent_MakeAvailable(SwiftTesting)
 ```
 
-## Define Your Test Executable
+## Define a test executable
 
-To build a test executable using `swift-testing`, define an executable target
-of the form `[YOURPROJECT]PackageTests`, set the executable suffix to be
-`.swift-testing`, and link to your project targets with `Testing`.
+To build a test executable using Swift Testing, define an executable target of
+the form `[YOURPROJECT]PackageTests`, set the executable suffix to be
+`.swift-testing`, and link to the `Testing` target as well as any project
+targets you wish to test.
 
 The following
 example shows what this might look like for a hypothetical project called
@@ -44,13 +46,10 @@ if(BUILD_TESTING)
 endif()
 ```
 
-## Add an Entry Point
+## Add an entry point
 
-You must define a custom source file with a `@main` entry point. This should be
-a separate source file that is included in your test executable's `SOURCES`
-list.
-
-The following example uses the SwiftPM entry point:
+You must include a source file in your test executable target with a
+`@main` entry point. The following example uses the SwiftPM entry point:
 
 ```swift
 import Testing
@@ -61,10 +60,10 @@ import Testing
     }
 }
 ```
+
 > [!WARNING]
 > The entry point is expected to change to an entry point designed for other
-> build systems prior to `swift-testing` v1.
-
+> build systems prior to the initial stable release of Swift Testing.
 
 ## Integrate with CTest
 

Documentation/README.md

@@ -1,4 +1,4 @@
-# swift-testing documentation
+# Swift Testing documentation
 
 <!--
 This source file is part of the Swift.org open source project
@@ -12,10 +12,10 @@ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 
 ## API and usage guides
 
-The detailed documentation for `swift-testing` can be found on the
+The detailed documentation for Swift Testing can be found on the
 [Swift Package Index](https://swiftpackageindex.com/apple/swift-testing/main/documentation/testing).
 There, you can delve into comprehensive guides, tutorials, and API references to
-make the most out of `swift-testing`.
+make the most out of this package.
 
 This documentation is generated using [DocC](https://github.com/apple/swift-docc)
 and is derived from symbol documentation in this project's source code as well
@@ -25,8 +25,8 @@ directory.
 
 ## Vision document
 
-The [Vision document](https://github.com/apple/swift-testing/blob/main/Documentation/Vision.md)
-for `swift-testing` offers a comprehensive discussion of the project's design
+The [Vision document](https://github.com/apple/swift-evolution/blob/main/visions/swift-testing.md)
+for Swift Testing offers a comprehensive discussion of the project's design
 principles and goals. 
 
 ## Development and contribution
@@ -38,11 +38,11 @@ principles and goals.
   provides guidance for developing and making project contributions.
 - [Style Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md)
   describes this project's guidelines for code and documentation style.
-- [SPI groups in swift-testing](https://github.com/apple/swift-testing/blob/main/Documentation/SPI.md)
+- [SPI groups in Swift Testing](https://github.com/apple/swift-testing/blob/main/Documentation/SPI.md)
   describes when and how the testing library uses Swift SPI.
 
 ## Project maintenance
 
 - The [Releases](https://github.com/apple/swift-testing/blob/main/Documentation/Releases.md)
   document describes the process of creating and publishing a new release of
-  `swift-testing`—a task which may be performed by project administrators.
+  Swift Testing — a task which may be performed by project administrators.

Documentation/Releases.md

@@ -1,6 +1,6 @@
-# How to create swift-testing releases
+# How to create a release of Swift Testing
 
-This document describes how to create a new release of swift-testing using git
+This document describes how to create a new release of Swift Testing using Git
 tags.
 
 > [!IMPORTANT]
@@ -9,13 +9,13 @@ tags.
 
 ## Version numbering
 
-swift-testing uses [semantic versioning](https://semver.org) numbers for its 
-open source releases. We use git _tags_ to publish new releases; we do not use
+Swift Testing uses [semantic versioning](https://semver.org) numbers for its
+open source releases. We use Git _tags_ to publish new releases; we don't use
 the GitHub [releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases)
 feature.
 
-At this time, all swift-testing releases are experimental, so the major version
-is always `0`. We are not using the patch component, so it is usually (if not
+At this time, all Swift Testing releases are experimental, so the major version
+is always `0`. We aren't using the patch component, so it's usually (if not
 always) `0`. The minor component should be incremented by one for each release.
 
 For example, if the current release is version `0.1.0` and you are publishing
@@ -69,9 +69,9 @@ For example, you can initialize a new package in an empty directory with:
 swift package init --enable-experimental-swift-testing
 ```
 
-And then modify the package's `Package.swift` file to point at your local clone
-of the swift-testing repository. Ensure that the package's test target builds
-and runs successfully with:
+Then modify the package's `Package.swift` file to point at your local clone of
+the Swift Testing repository. Ensure that the package's test target builds and
+runs successfully with:
 
 ```sh
 swift test
@@ -81,8 +81,8 @@ swift test
 > Be sure to test changes on both macOS and Linux using the most recent
 > main-branch Swift toolchain.   
 
-If changes to swift-testing are necessary for the build to succeed, open
-appropriate pull requests on GitHub, then rebase your tag branch after they are
+If changes to Swift Testing are necessary for the build to succeed, open
+appropriate pull requests on GitHub, then rebase your tag branch after they're
 merged.
 
 ## Committing changes and pushing the release
@@ -95,7 +95,7 @@ git push -u origin x.y.z
 ```
 
 The release is now live and publicly visible [here](https://github.com/apple/swift-testing/tags).
-Developers using Swift Package Manager and listing swift-testing as a dependency
+Developers using Swift Package Manager and listing Swift Testing as a dependency
 will automatically update to it.
 
 ## Oh no, I made a mistake…

Documentation/SPI.md

@@ -1,11 +1,12 @@
-# SPI groups in swift-testing
+# SPI groups in Swift Testing
 
-_Archived from <https://forums.swift.org/t/spi-groups-in-swift-testing/70236>_
+<!-- Archived from
+  <https://forums.swift.org/t/spi-groups-in-swift-testing/70236> -->
 
-This post describes the set of SPI groups used in swift-testing. In general, two
+This post describes the set of SPI groups used in Swift Testing. In general, two
 groups of SPI exist in the testing library:
 
-1. Interfaces that are not needed by test authors, but which may be needed by
+1. Interfaces that aren't needed by test authors, but which may be needed by
    tools that use the testing library such as Swift Package Manager; and
 1. Interfaces that are available for test authors to use, but which are
    experimental or under active development and which may be modified or removed
@@ -40,7 +41,7 @@ modified or removed at any time.
 
 ## API and ABI stability
 
-Once swift-testing reaches its 1.0 release, API changes will follow the same
+When Swift Testing reaches its 1.0 release, API changes will follow the same
 general rules as those in the Swift standard library: removal will be a last
 resort and will always be preceded by deprecation to allow tool and test authors
 time to migrate to newer interfaces.