New card-based home page

docs/articles/archive.md

@@ -0,0 +1,47 @@
+---
+uid: archive
+---
+
+# Archive
+
+These pages describe older versions of NUnit, features that were removed or deprecated, and tools that are no longer
+maintained. They are kept for reference, and for anyone still working with older versions.
+
+For the current version, start at the [documentation home page](../index.md).
+
+## Older versions of NUnit
+
+* [NUnit 2.x documentation](xref:legacydocs)
+* [Release notes before NUnit 3.5](xref:pre35releasenotes)
+* [Breaking changes up to NUnit 4.0](xref:breakingchanges)
+* [Migrating to NUnit 4](xref:migrationguidance)
+* [Upgrading from NUnit 2 and 3](nunit/getting-started/upgrading.md)
+* [Towards NUnit 4](xref:towardsnunit4)
+* [.NET Core and .NET Standard](nunit/getting-started/dotnet-core-and-dotnet-standard.md)
+
+## Deprecated and removed features
+
+* [AssertionHelper](nunit/writing-tests/AssertionHelper.md), deprecated in NUnit 3.7
+* [ListMapper](nunit/writing-tests/ListMapper.md), removed in NUnit 4.0
+* [Addin Replacement in the Framework](xref:addinreplacementintheframework), the move away from NUnit 2 add-ins
+* [Visual Studio Support](xref:visualstudiosupport), for Visual Studio 2003 and 2005 and the NUnit 2 GUI
+
+## Tools that are no longer maintained
+
+* [NUnit Xamarin Runners](xref:xamarinrunners)
+* [NUnit VS Test Generator](xref:vstestgenerator)
+* [NUnit Project Editor](https://github.com/nunit-legacy/nunit-project-editor/wiki/Project-Editor)
+
+## Older release notes
+
+* [Test Adapter V3 release notes](vs-test-adapter/AdapterV3-Release-Notes.md)
+* [Test Adapter V2 release notes](vs-test-adapter/AdapterV2-Release-Notes.md)
+* [Test Generator release notes for Visual Studio 2017 and 2019](vs-test-generator/TestGenerator-Release-Notes-VS2017-VS2019.md)
+* [Test Generator release notes for Visual Studio 2015](vs-test-generator/TestGenerator-Release-Notes-VS2015.md)
+
+## Developer history
+
+* [Notes Toward NUnit 4.0](developer-info/Notes-Toward-NUnit-4.0.md)
+* [NUnit 3.0 Architecture (2009)](xref:nunit3architecture2009)
+* [Packaging the V2 Adapter](developer-info/Packaging-the-V2-Adapter.md)
+* [Packaging the Installer](developer-info/Packaging-the-Installer.md), for the MSI installer that is no longer produced

docs/articles/developer-info/Packaging.md

@@ -0,0 +1,14 @@
+---
+uid: packaging
+---
+
+# Packaging
+
+These pages describe how the NUnit team packages and releases each component.
+
+* [Packaging the Framework](Packaging-the-Framework.md)
+* [Packaging the Console and Engine](Packaging-the-Console-and-Engine.md)
+* [Packaging the V3/V4 Adapter](Packaging-the-V3-and-V4-Adapter.md)
+* [Packaging Extensions](Packaging-Extensions.md)
+
+Instructions for packaging the V2 adapter and the MSI installer are in the [Archive](xref:archive).

docs/articles/developer-info/toc.yml

@@ -4,8 +4,6 @@
   href: Team-Practices.md
 - name: Specifications
   topicUid: specifications
-- name: Notes Toward NUnit 4.0
-  href: Notes-Toward-NUnit-4.0.md
 - name: Best Practices for XML Documentation
   href: Best-practices-for-XML-documentation.md
 - name: Coding Standards
@@ -14,15 +12,13 @@
   href: Contributions.md
 - name: Issue Tracking
   href: Issue-Tracking.md
+- name: Packaging
+  href: Packaging.md
 - name: Packaging Extensions
   href: Packaging-Extensions.md
 - name: Packaging the Console and Engine
   href: Packaging-the-Console-and-Engine.md
 - name: Packaging the Framework
   href: Packaging-the-Framework.md
-- name: Packaging the Installer
-  href: Packaging-the-Installer.md
-- name: Packaging the V2 Adapter
-  href: Packaging-the-V2-Adapter.md
 - name: Packaging the V3/V4 Adapter
   href: Packaging-the-V3-and-V4-Adapter.md

docs/articles/nunit-engine/Index.md

@@ -13,6 +13,7 @@ engine and run tests as required.
 > rather than using one of the many existing test runners in the ecosystem. If you are looking to simply run tests that
 > you have written, see the [running tests](xref:runningtests) section.
 
-The engine exposes [an API](xref:testengineapi) designed to be used by test runners, which will be maintained in a
+To start using the engine in your own runner, see [Getting Started](xref:gettingstartedengine). The engine exposes
+[an API](xref:testengineapi) designed to be used by test runners, which will be maintained in a
 backwards-compatible fashion wherever possible. The engine also hosts various extension points, to allow further
 customization.

docs/articles/nunit-engine/github-release-notes.md

@@ -0,0 +1,14 @@
+---
+uid: consoleenginegithubreleasenotes
+---
+
+# Console and Engine Release Notes
+
+From version 3.18.0, the release notes for the NUnit Console and Engine are published with each release on GitHub:
+
+**[NUnit Console and Engine releases on GitHub](https://github.com/nunit/nunit-console/releases)**
+
+Each release there lists the issues that were fixed and links to the downloads, including the NUnit Console and
+Engine 4.0 pre-releases.
+
+For version 3.17.0 and earlier, see the [release notes up to 3.17](xref:consoleenginereleasenotes).

docs/articles/nunit-engine/release-notes.md

@@ -6,6 +6,10 @@ uid: consoleenginereleasenotes
 
 # Console and Engine Release Notes
 
+> [!NOTE]
+> This page covers version 3.17.0 and earlier. The release notes for later versions are published on GitHub, see
+> [Console and Engine Release Notes](xref:consoleenginegithubreleasenotes).
+
 ## NUnit Console & Engine 3.17.0 - January 4, 2024
 
 This release adds support for .net 8 by adding a missing agent.

docs/articles/nunit-engine/toc.yml

@@ -7,5 +7,5 @@
 - name: Engine Extensions
   href: extensions/toc.yml
   topicHref: extensions/Index.md
-- name: Release Notes 
-  href: release-notes.md
+- name: Release Notes
+  href: github-release-notes.md

docs/articles/nunit/getting-started/toc.yml

@@ -2,11 +2,6 @@
   href: installation.md
 - name: Downloading
   href: downloading.md
-- name: Upgrading
-  href: upgrading.md
 - name: Samples
   href: samples.md
-- name: Breaking Changes
-  topicUid: breakingchanges
-- name: .NET Core and .NET Standard
-  href: dotnet-core-and-dotnet-standard.md
+

docs/articles/nunit/intro.md

@@ -4,11 +4,27 @@ uid: intro
 
 # NUnit Documentation
 
-This documentation covers NUnit 3.0 and higher.
+NUnit is the open-source unit-testing framework for all .NET languages. This section documents the NUnit framework,
+NUnitLite and the NUnit Console, from NUnit 3 up to the current version, NUnit 5.
 
-Where applicable, we have marked sections with the version in which a feature first appeared.
+Most of the content applies to all these versions. Where a feature was added or changed in a specific version, the
+page says so, for example "This constraint was added in NUnit 4.2". Behavior from earlier versions is described in
+notes or in sections such as *NUnit 4 and earlier*.
 
-If you are new to NUnit, we suggest you begin by reading the Getting Started section of this site. Those who have used
-earlier releases may want to begin with the Upgrading section.
+## Where to start
 
-See the [Release Notes](xref:frameworkreleasenotes) for more information on each release.
+* **New to NUnit?** Start with [Installation](xref:installation) to create a test project, and then
+  [Ordinary Tests](xref:ordinarytests) to write your first test.
+* **Moving to NUnit 5?** See [What's new in NUnit 5](xref:v5newfeatures) and
+  [the breaking changes in NUnit 5](xref:v5breakingchanges).
+* **Looking for a specific attribute, assertion or constraint?** See [Attributes](writing-tests/attributes.md),
+  [Assertions](xref:assertions) and [Constraints](xref:constraints).
+* **What changed in a release?** See the [release notes](xref:frameworkreleasenotes).
+
+The [documentation home page](../../index.md) gives an overview of everything, including the test adapter, the
+analyzers and the NUnit engine.
+
+## NUnit 2
+
+NUnit 2 is a different product, with its own design and its own documentation. It is not covered here. Its
+documentation is kept in the [Archive](xref:legacydocs).

docs/articles/nunit/license.md

@@ -1,6 +1,9 @@
 # NUnit License
 
-## Copyright (c) 2004-2021 Charlie Poole, Rob Prouse and Contributors.
+> [!NOTE]
+> This is the former license. Now replaced with an [MIT license](https://github.com/nunit/docs/blob/master/LICENSE.md).
+
+## Copyright (c) 2004-2021 Charlie Poole, Rob Prouse and Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

docs/articles/nunit/release-notes/toc.yml

@@ -1,10 +1,4 @@
 - name: Framework
   href: framework.md
 - name: Console and Engine
-  topicUid: consoleenginereleasenotes
-- name: Migration Guidance
-  topicUid: migrationguidance
-- name: Breaking Changes
-  topicUid: breakingchanges
-- name: Pre-3.5 Release notes
-  href: Pre-3.5-Release-Notes.md
+  topicUid: consoleenginegithubreleasenotes

docs/articles/nunit/running-tests/Console-Runner.md

@@ -3,6 +3,8 @@
 The nunit3-console.exe program is a text-based runner for listing and running our tests from the command-line. It is
 able to run all NUnit 3.0 or higher tests natively and can run NUnit 2.x tests if the v2 driver is installed.
 
+All the options are described in [Console Command Line](xref:consolecommandline).
+
 This runner is useful for automation of tests and integration into other systems. It automatically saves its results in
 XML format, allowing you to produce reports or otherwise process the results. The following is a screenshot of the
 console program output.

docs/articles/nunit/running-tests/NUnitLite-Runner.md

@@ -52,6 +52,8 @@ dotnet run
 If you install the NUnitLite runner via the NuGet package, steps 2 is handled automatically. Both assemblies are
 installed and referenced for you.
 
+All the options are described in [NUnitLite Options](NUnitLite-Options.md).
+
 ## NUnitLite Output
 
 As seen in the following screen shot, the output from an NUnitLite run is quite similar to that from the console runner.

docs/articles/nunit/technical-notes/nunit-internals/toc.yml

@@ -19,8 +19,6 @@
   href: Attribute-Hierarchy.md
 - name: Test Discovery And Execution
   href: Test-Discovery-And-Execution.md
-- name: NUnit 3.0 Architecture (2009)
-  href: NUnit-3.0-Architecture-(2009).md
 - name: Specifications
   href: specs/toc.yml
   topicHref: specs/Specifications.md

docs/articles/nunit/technical-notes/usage/Trace-and-Debug-Output.md

@@ -100,6 +100,9 @@ test fixture/class.
 
 If you like you can change that to another kind of listener.
 
+For how the test adapter shows this output in Visual Studio and `dotnet test`, see
+[Trace and Debug Output in the adapter](../../../vs-test-adapter/Trace-and-Debug.md).
+
 ## Discussion and source
 
 This issue has been discussed at [Issue 718](https://github.com/nunit/nunit3-vs-adapter/issues/718) and

docs/articles/nunit/technical-notes/usage/Usage-Notes.md

@@ -5,10 +5,9 @@
 * [Assembly Isolation](Assembly-Isolation.md)
 * [Configuration Files](Configuration-Files.md)
 * [XML Formats](XML-Formats.md)
-* [Visual Studio Support](Visual-Studio-Support.md)
+* [NUnit Test Projects](xref:nunittestprojects)
 * [SetUp and TearDown](SetUp-and-TearDown.md)
 * [Parameterized Tests](Parameterized-Tests.md)
-* [Addin Replacement in the Framework](Addin-Replacement-in-the-Framework.md)
 * [Counting Tests](Counting-Tests.md)
 * [Framework Parallel Test Execution](Framework-Parallel-Test-Execution.md)
 * [Engine Parallel Test Execution](Engine-Parallel-Test-Execution.md)

docs/articles/nunit/technical-notes/usage/toc.yml

@@ -1,7 +1,5 @@
 - name: Usage Notes
   href: Usage-Notes.md
-- name: Addin Replacement in the Framework
-  href: Addin-Replacement-in-the-Framework.md
 - name: Assembly Isolation
   href: Assembly-Isolation.md
 - name: Configuration Files
@@ -30,7 +28,5 @@
   href: Test-Result-XML-Format.md
 - name: Trace and Debug Output
   href: Trace-and-Debug-Output.md
-- name: Visual Studio Support
-  href: Visual-Studio-Support.md
 - name: XML Formats
   href: XML-Formats.md

docs/articles/nunit/toc.yml

@@ -4,10 +4,6 @@
   href: V5NewFeatures.md
 - name: NUnit 5 Breaking Changes
   href: V5BreakingChanges.md
-- name: NUnit 4 plans
-  href: Towards-NUnit4.md
-- name: Migration Guidance
-  uid: migrationguidance
 - name: Release Notes
   href: release-notes/toc.yml
   topicHref: release-notes/framework.md
@@ -18,7 +14,7 @@
   topicHref: getting-started/installation.md
 - name: Writing Tests
   href: writing-tests/toc.yml
-  topicHref: writing-tests/attributes.md
+  topicHref: writing-tests/ordinary-tests.md
 - name: Running Tests
   href: running-tests/toc.yml
   topicHref: running-tests/Index.md

docs/articles/nunit/writing-tests/automating-tests.md

@@ -0,0 +1,61 @@
+---
+uid: automatingtests
+---
+
+# Automating Tests
+
+With [data driven tests](xref:datadriventests) you write out every test case yourself. NUnit can also do that work for
+you: you describe the possible values for each parameter, and NUnit generates the test cases. This is a good way to
+cover many inputs with very little code.
+
+## Every combination with [Values]
+
+Put [`[Values]`](xref:attribute-values) on each parameter. By default NUnit runs the test once for every combination
+of the values, so the example below produces 3 × 2 = 6 test cases.
+
+[!code-csharp[AutomatingCombinatorial](~/snippets/Snippets.NUnit/WritingTestsGuideExamples.cs#AutomatingCombinatorial)]
+
+For `bool` and `enum` parameters you can leave out the values: `[Values] bool flag` gives you both `true` and
+`false`.
+
+## A range of numbers with [Range]
+
+Use [`[Range]`](xref:attribute-range) to generate numbers from a start value to an end value, with an optional step.
+This example runs with -10, -5, 0, 5 and 10.
+
+[!code-csharp[AutomatingRange](~/snippets/Snippets.NUnit/WritingTestsGuideExamples.cs#AutomatingRange)]
+
+## Random numbers with [Random]
+
+Use [`[Random]`](xref:attribute-random) to have NUnit pick values for you. This is useful for checking rules that must
+hold for *any* input, such as `a + b == b + a`. NUnit records the random seed it used in the test results, so a failing run can be reproduced.
+
+[!code-csharp[AutomatingRandom](~/snippets/Snippets.NUnit/WritingTestsGuideExamples.cs#AutomatingRandom)]
+
+To create random values in the test code itself, use the [Randomizer](xref:randomizermethods) from
+`TestContext.CurrentContext.Random`. It uses the same seed, so these values can be reproduced too.
+
+## Keeping the number of tests down
+
+Combinations grow fast: three parameters with ten values each give a thousand test cases. NUnit has two attributes that
+change how the values are combined:
+
+- [`[Pairwise]`](xref:attribute-pairwise) generates just enough cases so that every *pair* of values is tested
+  together at least once. Most bugs are caused by one value or by two values together, so this finds most of them
+  with far fewer tests.
+- [`[Sequential]`](xref:attribute-sequential) uses the first value of each parameter together, then the second values,
+  and so on, instead of all combinations.
+
+[!code-csharp[AutomatingPairwise](~/snippets/Snippets.NUnit/WritingTestsGuideExamples.cs#AutomatingPairwise)]
+
+## Theories
+
+A [`[Theory]`](xref:attribute-theory) goes one step further: you state something that must be true for all data
+points, and NUnit tries it with every suitable value you have marked with [`[Datapoint]`](xref:attribute-datapoint)
+or [`[DatapointSource]`](xref:attribute-datapointsource).
+
+## Next steps
+
+- [Combinatorial](xref:attribute-combinatorial), [Pairwise](xref:attribute-pairwise) and
+  [Sequential](xref:attribute-sequential) describe the combining strategies in detail.
+- [Parameterized tests](xref:parameterizedtests) describes all the details of how parameterized tests work.