Document xunit v3 migration path

README.md

@@ -7,6 +7,10 @@ Xunit.SkippableFact
 This project allows for Xunit tests that can determine during execution that they should report a "skipped" result.
 This can be useful when a precondition is not satisfied, or the test is over functionality that does not exist on the platform being tested.
 
+This package targets Xunit v2.
+Xunit v3 has skipping built-in.
+See [our Xunit v3 migration doc](https://aarnott.github.io/Xunit.SkippableFact/docs/xunit-v3.html).
+
 ## Installation
 
 This project is available as a [NuGet package][NuPkg]

docfx/docfx.json

@@ -1,48 +1,53 @@
 {
-	"metadata": [
-		{
-			"src": [
-				{
-					"src": "../src/Xunit.SkippableFact",
-					"files": [
-						"**/*.csproj"
-					]
-				}
-			],
-			"dest": "api"
-		}
-	],
-	"build": {
-		"content": [
-			{
-				"files": [
-					"**/*.{md,yml}"
-				],
-				"exclude": [
-					"_site/**"
-				]
-			}
-		],
-		"resource": [
-			{
-				"files": [
-					"images/**"
-				]
-			}
-		],
-		"xref": [
-			"https://learn.microsoft.com/en-us/dotnet/.xrefmap.json"
-		],
-		"output": "_site",
-		"template": [
-			"default",
-			"modern"
-		],
-		"globalMetadata": {
-			"_appName": "Xunit.SkippableFact",
-			"_appTitle": "Xunit.SkippableFact",
-			"_enableSearch": true,
-			"pdf": false
-		}
-	}
+  "metadata": [
+    {
+      "src": [
+        {
+          "src": "../src/Xunit.SkippableFact",
+          "files": [
+            "**/*.csproj"
+          ]
+        }
+      ],
+      "dest": "api"
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": [
+          "**/*.{md,yml}"
+        ],
+        "exclude": [
+          "_site/**"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "images/**"
+        ]
+      }
+    ],
+    "xref": [
+      "https://learn.microsoft.com/en-us/dotnet/.xrefmap.json"
+    ],
+    "output": "_site",
+    "template": [
+      "default",
+      "modern"
+    ],
+    "globalMetadata": {
+      "_appName": "Xunit.SkippableFact",
+      "_appTitle": "Xunit.SkippableFact",
+      "_enableSearch": true,
+      "pdf": false
+    },
+    "markdownEngineProperties": {
+      "markdigExtensions": [
+        "footnotes"
+      ]
+    }
+  }
 }

docfx/docs/toc.yml

@@ -2,4 +2,4 @@
   href: features.md
 - name: Getting Started
   href: getting-started.md
-
+- href: xunit-v3.md

docfx/docs/xunit-v3.md

@@ -0,0 +1,16 @@
+# Xunit v3 Migration
+
+Xunit v3 has skipping built-in, so there is no need for Xunit.SkippableFact.
+As part of upgrading from Xunit v2 to v3, you should remove your package reference on Xunit.SkippableFact.
+
+The following provides a guide for switching your use of Xunit.SkippableFact to Xunit v3 when you update your Xunit dependency.
+
+Xunit.SkippableFact API | Xunit v3 API
+--|--
+@Xunit.Skip.If* | Assert.SkipWhen
+@Xunit.Skip.IfNot* | Assert.SkipUnless
+@Xunit.SkipException | Xunit.Sdk.SkipException
+@Xunit.SkippableFactAttribute | Xunit.FactAttribute[^1]
+@Xunit.SkippableTheoryAttribute | Xunit.TheoryAttribute[^1]
+
+[^1]: Xunit's built-in attributes are sufficient. Although they lack the ability to take a list of exception types that should produce a Skipped result. This [may come in the future](https://github.com/xunit/xunit/issues/3101).

docfx/toc.yml

@@ -2,3 +2,5 @@
   href: docs/
 - name: API
   href: api/
+- name: GitHub
+  href: https://github.com/AArnott/Xunit.SkippableFact