Remove Bug.Relationship. (#394)

This PR removes the `Bug.Relationship` type and corresponding
`relationship` property and accoutrements.

We had planned to expose this information so that developers could
provide finer-grained metadata about related bugs that could be surfaced
in `swift test` or IDEs like VSCode.

In practice, we've struggled to figure out how this information could
actually be used: a tool like `swift test` doesn't have write access to
a developer's bug tracking software, so it couldn't go update a bug with
a comment saying "this issue has started occurring again" or something
like that.

We are interested in re-exposing this API or something similar in the
future, but for our initial release we are removing it.

### 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.

Author: grynspan

Sources/Testing/Testing.docc/AssociatingBugs.md

@@ -25,9 +25,9 @@ specific bugs with tests that reproduce them or verify they are fixed.
 
 ## Associate a bug with a test
 
-To associate a bug with a test, use the ``Trait/bug(_:relationship:_:)-86mmm``
-or ``Trait/bug(_:relationship:_:)-3hsi5`` function. The first argument to this
-function is the bug's _identifier_ in its bug-tracking system:
+To associate a bug with a test, use the ``Trait/bug(_:_:)-2u8j9`` or
+``Trait/bug(_:_:)-7mo2w`` function. The first argument to this function is the
+bug's _identifier_ in its bug-tracking system:
 
 ```swift
 @Test("Food truck engine works", .bug("12345"), .bug(67890))
@@ -43,54 +43,12 @@ specified as a string, it must be parseable as an unsigned integer or as a URL.
 For more information on the formats recognized by the testing library, see
 <doc:BugIdentifiers>.
 
-## Specify the relationship between a bug and a test
-
-By default, the nature of the relationship between a bug and a test is
-unspecified. All the testing library knows about such relationships is that they
-exist.
-
-It is possible to customize the relationship between a bug and a test. Doing so
-allows the testing library to make certain assumptions, such as that a test is
-expected to fail, or that a failure indicates a regression that requires
-attention from a developer.
-
-To specify how a bug is related to a test, use the `relationship` parameter of
-the ``Trait/bug(_:relationship:_:)-86mmm`` or
-``Trait/bug(_:relationship:_:)-3hsi5`` function. For example, to indicate that a
-test was written to verify a previously-fixed bug, one would specify
-`.verifiesFix`:
-
-```swift
-@Test("Food truck engine works", .bug("12345", relationship: .verifiesFix))
-func engineWorks() async {
-  var foodTruck = FoodTruck()
-  await foodTruck.engine.start()
-  #expect(foodTruck.engine.isRunning)
-}
-```
-
-### Kinds of relationship
-
-The testing library defines several kinds of common bug/test relationship:
-
-| Relationship | Use when… |
-|-|-|
-| `.uncoveredBug` | … a test run failed, uncovering the bug in question. |
-| `.reproducesBug` | … a bug was previously filed and the test was written to demonstrate it. |
-| `.verifiesFix` | … a bug has been fixed and the test shows that it no longer reproduces. |
-| `.failingBecauseOfBug` | … a test was previously passing, but now an unrelated bug is causing it to fail. |
-| `.unspecified` | … no other case accurately describes the relationship. |
-
-<!-- Keep `.unspecified` as the last row above in order to imply it is a
-fallback. -->
-
-## Adding comments to associated bugs
+## Add comments to associated bugs
 
 A bug identifier may be insufficient to uniquely and clearly identify a bug
 associated with a test. Bug trackers universally provide a "title" field for
 bugs that is not visible to the testing library. To add a bug's title to a test,
-include it after the bug's identifier and (optionally) its relationship to the
-test:
+include it after the bug's identifier:
 
 ```swift
 @Test(

Sources/Testing/Testing.docc/EnablingAndDisabling.md

@@ -83,16 +83,15 @@ func isCold() async throws { ... }
 ```
 
 If a test is disabled because of a problem for which there is a corresponding
-bug report, you can use the ``Trait/bug(_:relationship:_:)-86mmm`` or
-``Trait/bug(_:relationship:_:)-3hsi5`` function with the relationship
-``Bug/Relationship-swift.enum/failingBecauseOfBug``:
+bug report, you can use the ``Trait/bug(_:_:)-2u8j9`` or
+``Trait/bug(_:_:)-7mo2w`` function to show the relationship:
 
 ```swift
 @Test(
   "Ice cream is cold",
   .enabled(if: Season.current == .summer),
   .disabled("We ran out of sprinkles"),
-  .bug("#12345", relationship: .failingBecauseOfBug)
+  .bug("12345")
 )
 func isCold() async throws { ... }
 ```

Sources/Testing/Testing.docc/Traits.md

@@ -46,8 +46,8 @@ HIDDEN: .serialized is experimental SPI pending feature review.
 - <doc:AssociatingBugs>
 - <doc:BugIdentifiers>
 - ``Tag()``
-- ``Trait/bug(_:relationship:_:)-86mmm``
-- ``Trait/bug(_:relationship:_:)-3hsi5``
+- ``Trait/bug(_:_:)-2u8j9``
+- ``Trait/bug(_:_:)-7mo2w``
 
 ### Creating custom traits
 

Sources/Testing/Testing.docc/Traits/Trait.md

@@ -31,8 +31,8 @@ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 
 ### Associating bugs
 
-- ``Trait/bug(_:relationship:_:)-86mmm``
-- ``Trait/bug(_:relationship:_:)-3hsi5``
+- ``Trait/bug(_:_:)-2u8j9``
+- ``Trait/bug(_:_:)-7mo2w``
 
 ### Adding information to tests
 - ``Trait/comments``

Sources/Testing/Traits/Bug.swift

@@ -12,57 +12,15 @@
 ///
 /// To add this trait to a test, use one of the following functions:
 ///
-/// - ``Trait/bug(_:relationship:_:)-86mmm``
-/// - ``Trait/bug(_:relationship:_:)-3hsi5``
+/// - ``Trait/bug(_:_:)-86mmm``
+/// - ``Trait/bug(_:_:)-3hsi5``
 public struct Bug {
   /// The identifier of this bug in the associated bug-tracking system.
   ///
   /// For more information on how the testing library interprets bug
   /// identifiers, see <doc:BugIdentifiers>.
   public var identifier: String
 
-  /// An enumeration describing the relationship of a bug to a test.
-  ///
-  /// For more information on how the testing library uses bug relationships,
-  /// see <doc:AssociatingBugs>.
-  public enum Relationship: Sendable {
-    /// The relationship between the test and this bug is unspecified.
-    ///
-    /// Use this relationship to describe a bug that is related to a test, but
-    /// not in any specific way.
-    case unspecified
-
-    /// The test uncovered this bug.
-    ///
-    /// Use this relationship to describe a bug that was filed as a result of a
-    /// test failing.
-    case uncoveredBug
-
-    /// The test reproduces the bug.
-    ///
-    /// Use this relationship to describe a bug that the test is able to
-    /// reproduce consistently.
-    case reproducesBug
-
-    /// The test verifies that the bug has been fixed.
-    ///
-    /// Use this relationship when the associated test is meant to verify that
-    /// the bug has been fixed.
-    case verifiesFix
-
-    /// The test is failing because of the bug.
-    ///
-    /// Use this relationship when the associated test is not directly related
-    /// to the bug, but is failing because the bug has not been fixed yet.
-    case failingBecauseOfBug
-  }
-
-  /// The relationship between the bug and the associated test.
-  ///
-  /// For more information on how the testing library uses bug relationships,
-  /// see <doc:AssociatingBugs>.
-  public var relationship: Relationship
-
   /// An optional, user-specified comment describing this trait.
   public var comment: Comment?
 }
@@ -83,12 +41,9 @@ extension Bug: Equatable, Hashable, Comparable {
   }
 }
 
-extension Bug.Relationship: Equatable, Hashable {}
-
 // MARK: - Codable
 
 extension Bug: Codable {}
-extension Bug.Relationship: Codable {}
 
 // MARK: - Trait, TestTrait, SuiteTrait
 
@@ -105,14 +60,11 @@ extension Trait where Self == Bug {
   ///   - identifier: The identifier of this bug in the associated bug-tracking
   ///     system. For more information on how this value is interpreted, see the
   ///     documentation for ``Bug``.
-  ///   - relationship: The relationship between the bug and the associated
-  ///     test. The default value is
-  ///     ``Bug/Relationship-swift.enum/unspecified``.
   ///   - comment: An optional, user-specified comment describing this trait.
   ///
   /// - Returns: An instance of ``Bug`` representing the specified bug.
-  public static func bug(_ identifier: String, relationship: Bug.Relationship = .unspecified, _ comment: Comment? = nil) -> Self {
-    Self(identifier: identifier, relationship: relationship, comment: comment)
+  public static func bug(_ identifier: String, _ comment: Comment? = nil) -> Self {
+    Self(identifier: identifier, comment: comment)
   }
 
   /// Construct a bug to track with a test.
@@ -121,14 +73,11 @@ extension Trait where Self == Bug {
   ///   - identifier: The identifier of this bug in the associated bug-tracking
   ///     system. For more information on how this value is interpreted, see the
   ///     documentation for ``Bug``.
-  ///   - relationship: The relationship between the bug and the associated
-  ///     test. The default value is
-  ///     ``Bug/Relationship-swift.enum/unspecified``.
   ///   - comment: An optional, user-specified comment describing this trait.
   ///
   /// - Returns: An instance of ``Bug`` representing the specified bug.
-  public static func bug(_ identifier: some Numeric, relationship: Bug.Relationship = .unspecified, _ comment: Comment? = nil) -> Self {
-    Self(identifier: String(describing: identifier), relationship: relationship, comment: comment)
+  public static func bug(_ identifier: some Numeric, _ comment: Comment? = nil) -> Self {
+    Self(identifier: String(describing: identifier), comment: comment)
   }
 }
 

Sources/Testing/Traits/Comment.swift

@@ -18,8 +18,7 @@
 /// or `@Suite` attribute. See <doc:AddingComments> for more details.
 ///
 /// - Note: This type is not intended to reference bugs related to a test.
-///   Instead, use ``Trait/bug(_:relationship:_:)-86mmm`` or
-///   ``Trait/bug(_:relationship:_:)-3hsi5``.
+///   Instead, use ``Trait/bug(_:_:)-2u8j9`` or ``Trait/bug(_:_:)-7mo2w``.
 public struct Comment: RawRepresentable, Sendable {
   /// The single comment string contained in this instance.
   ///
@@ -122,8 +121,7 @@ extension Trait where Self == Comment {
   ///   comment.
   ///
   /// - Note: This function is not intended to reference bugs related to a test.
-  ///   Instead, use ``Trait/bug(_:relationship:_:)-86mmm`` or
-  ///   ``Trait/bug(_:relationship:_:)-3hsi5``.
+  ///   Instead, use ``Trait/bug(_:_:)-2u8j9`` or ``Trait/bug(_:_:)-7mo2w``.
   public static func comment(_ comment: String) -> Self {
     Self(rawValue: comment, kind: .trait)
   }

Tests/TestingTests/EventRecorderTests.swift

@@ -282,7 +282,7 @@ struct EventRecorderTests {
 
   @Test(
     "JUnitXMLRecorder outputs valid XML",
-    .bug("https://github.com/apple/swift-testing/issues/254", relationship: .verifiesFix)
+    .bug("https://github.com/apple/swift-testing/issues/254")
   )
   func junitXMLIsValid() async throws {
     let stream = Stream()

Tests/TestingTests/Test.SnapshotTests.swift

@@ -94,7 +94,7 @@ struct Test_SnapshotTests {
     #expect(snapshot.associatedBugs.first == Self.bug)
   }
 
-  private static let bug: Bug = Bug.bug(12345, relationship: .failingBecauseOfBug, "Lorem ipsum")
+  private static let bug: Bug = Bug.bug(12345, "Lorem ipsum")
 
   @available(_clockAPI, *)
   @Test("timeLimit property", .timeLimit(duration))

Tests/TestingTests/Traits/BugTests.swift

@@ -57,7 +57,7 @@ struct BugTests {
 
   @Test("Test.associatedBugs property")
   func testAssociatedBugsProperty() {
-    let test = Test(.bug(12345), .disabled(), .bug(67890), .bug(24680, relationship: .uncoveredBug), .bug(54321, relationship: .verifiesFix)) {}
+    let test = Test(.bug(12345), .disabled(), .bug(67890), .bug(24680), .bug(54321)) {}
     let bugIdentifiers = test.associatedBugs
     #expect(bugIdentifiers.count == 4)
     #expect(bugIdentifiers[0].identifier == "12345")
@@ -66,32 +66,16 @@ struct BugTests {
     #expect(bugIdentifiers[3].identifier == "54321")
   }
 
-  @Test(".bug() with String and relationship")
-  func bugWithStringAndRelationship() {
-    let trait = Bug.bug("12345", relationship: .uncoveredBug)
-    #expect((trait as Any) is Bug)
-    #expect(trait.identifier == "12345")
-    #expect(trait.relationship == .uncoveredBug)
-  }
-
-  @Test(".bug() with number and relationship")
-  func bugWithNumericAndRelationship() {
-    let trait = Bug.bug(67890, relationship: .uncoveredBug)
-    #expect((trait as Any) is Bug)
-    #expect(trait.identifier == "67890")
-    #expect(trait.relationship == .uncoveredBug)
-  }
-
   @Test("Bug hashing")
   func hashing() {
-    let traits: Set<Bug> = [.bug(12345), .bug(12345), .bug(12345, relationship: .uncoveredBug), .bug("67890")]
+    let traits: Set<Bug> = [.bug(12345), .bug(12345), .bug(12345), .bug("67890")]
     #expect(traits.count == 2)
   }
 
 #if canImport(Foundation)
   @Test("Encoding/decoding")
   func encodingAndDecoding() throws {
-    let original = Bug.bug(12345, relationship: .failingBecauseOfBug, "Lorem ipsum")
+    let original = Bug.bug(12345, "Lorem ipsum")
     let copy = try JSON.encodeAndDecode(original)
     #expect(original == copy)
   }