ceedling 1.0.1 → 1.1.0

data/{plugins/report_tests_log_factory/README.md → docs/mkdocs/plugins/report-tests-log-factory.md}

@@ -1,8 +1,8 @@
-# Ceedling Plugin: Test Suite Report Log Factory
+# Test Suite Report Log Factory
 
 Generate one or more built-in test suite reports — JSON, JUnit XML, CppUnit XML, or HTML — or create your own.
 
-# Plugin Overview
+## Plugin Overview
 
 Test reports are handy for all sorts of reasons. Various build and reporting tools are able to generate, visualize, or otherwise process results encoded in handy container formats including JSON and XML.
 
@@ -13,11 +13,11 @@ This plugin generates one or more of up to four available test suite report form
 1. CppUnit XML
 1. HTML
 
-This plugin generates reports after test builds, storing them in your project `artifacts/` build path.
+This plugin generates reports after test builds, storing them in your project `artifacts/` build path. It also regenerates reports when `ceedling summary` is executed, building reports from the test results already present.
 
 With a limited amount of Ruby code, you can also create your own report without creating an entire Ceedling plugin.
 
-# _User Beware_
+## _User Beware_
 
 Test reports often lack well managed standards or even much documentation at all. Different revisions of the formats exist as do different flavors of the same version produced by different tools.
 
@@ -26,7 +26,7 @@ If a test report produced by this plugin does not work for your needs or is not
 1. Use a script or other tool to post-process the report into a format that works for you. You might be surprised how many of these hacks are commonly necessary and exist peppered throughout online forums. You can incorporate any such post-processing step by enabling the `command_hooks` Ceedling plugin (lower in the plugin list than this plugin) and configuring a Ceedling tool to run the needed transformation.
 1. Use Ceedling's abilities plus features of this plugin (documented below) to generate your own test report with a minimal amount of Ruby code.
 
-# Setup
+## Setup
 
 Enable the plugin in your Ceedling project file by adding `report_tests_log_factory` to the list of enabled plugins.
 
@@ -38,7 +38,7 @@ Enable the plugin in your Ceedling project file by adding `report_tests_log_fact
 
 All generated reports are written to `<build root>/artifacts/<context>`. Your Ceedling project file specifies `<build root>` as a required entry for any build. Your build's context defaults to `test`. Certain other test build plugins (e.g. GCov) provide a different context (e.g. `gcov`) for test builds, generally named after themselves. That is, for example, if this plugin is used in conjunction with a GCov coverage build, the reports will end up in a subdirectory other than `test/`, `gcov/`.
 
-# Configuration
+## Configuration
 
 Enable the reports you wish to generate — `json`, `junit`, and/or `cppunit` — within the `:report_tests_log_factory` ↳ `:reports` configuration list.
 
@@ -71,9 +71,13 @@ To change the output filename, specify it with the `:filename` key beneath the r
     :filename: 'more_better_filename.ext'
 ```
 
-# Built-in Reports
+## Built-in Reports
 
-## Execution duration values
+Each report is populated with a name, using `:project` ↳ `:name` from your configuration if set.
+
+Those reports that support build time or test suite execution time “stopwatch” values include them.
+
+### Execution duration values
 
 Some test reporting formats include the execution time (duration) for aspects of a test suite run. Various granularities exist from the total time for all tests to the time of each suite (per the relevant defition of a suite) to the time required to run individual test cases. See _CeedlingPacket_ for the details on time duration values.
 
@@ -91,15 +95,15 @@ _Note:_ Most test cases are quite short, and most computers are quite fast. As s
 
 [Unity]: https://github.com/ThrowTheSwitch/Unity
 
-## JSON Format
+### JSON Format
 
 [JSON] is “a lightweight data-interchange format.” JSON serializes common data structures into a human readable form. The format has several pros, including the ability for entirely different programming languages to ingest JSON and recreate these data structures. As such, this makes JSON a good report generation option as the result can be easily programmatically manipulated and put to use.
 
-Something like XML is a general purpose structure for, well, structuring data. XML has enough formality that XML formats can be validated with general purpose tools plus much more. JSON is much more flexible but rather tied to the data it encodes. Small changes to a data structure can have big impacts.
+Something like XML is a general purpose structure for, well, structuring data. XML has enough formality that XML formats can be validated with general purpose tools plus much more. JSON is much more flexible but is rather tied to the data it encodes. Small changes to a data structure can have big impacts.
 
 The JSON this plugin generates uses an ad hoc set of data structures following no standard — though any other test framework outputting test results in JSON may look fairly similar.
 
-### Example JSON configuration YAML
+#### Example JSON configuration YAML
 
 ```yaml
 :plugins:
@@ -117,7 +121,7 @@ The JSON this plugin generates uses an ad hoc set of data structures following n
 
 [JSON]: https://www.json.org/
 
-### Example JSON test report
+#### Example JSON test report
 
 In the following example a single test file _TestUsartModel.c_ exercised four test cases. Two test cases passed, one test case failed, and one test case was ignored.
 
@@ -127,6 +131,8 @@ In the following example a single test file _TestUsartModel.c_ exercised four te
 
 ```json
 {
+  "Name": "Ceedling Test Suite",
+  "BuildDuration": 123.4,
   "FailedTests": [
     {
       "file": "test/TestUsartModel.c",
@@ -160,14 +166,14 @@ In the following example a single test file _TestUsartModel.c_ exercised four te
 }
 ```
 
-## JUnit XML Format
+### JUnit XML Format
 
 [JUnit] holds a certain position among testing tools. While it is an xUnit-style framework specific to unit testing Java, it has influenced how Continuous Integration build tools operate, and its [JUnit XML report format][junit-xml-format] has become something of a defacto standard for test reports in any language. The JUnit XML format has been revised in various ways over time but generally has more available documentation than some other formats.
 
 [JUnit]: https://junit.org/
 [junit-xml-format]: https://docs.getxray.app/display/XRAY/Taking+advantage+of+JUnit+XML+reports
 
-### Example JUnit configuration YAML
+#### Example JUnit configuration YAML
 
 ```yaml
 :plugins:
@@ -183,7 +189,7 @@ In the following example a single test file _TestUsartModel.c_ exercised four te
     :filename: junit_tests_report.xml
 ```
 
-### Example JUnit test report
+#### Example JUnit test report
 
 In the following example a single test file _TestUsartModel.c_ exercised four test cases. Two test cases passed, one test case failed, and one test case was ignored (a.k.a. “skipped” in JUnit lingo).
 
@@ -195,7 +201,7 @@ In mapping a Ceedling test suite to JUnit convetions, a Ceedling _test file_ bec
 
 ```xml
 <?xml version="1.0" encoding="utf-8" ?>
-<testsuites tests="4" failures="1" time="0.331">
+<testsuites name="Ceedling Test Suite" tests="4" failures="1" time="0.331">
   <testsuite name="test/TestUsartModel" tests="4" failures="1" skipped="1" errors="0" time="0.331">
     <testcase name="testGetBaudRateRegisterSettingShouldReturnAppropriateBaudRateRegisterSetting" time="0.000"/>
     <testcase name="testShouldReturnErrorMessageUponInvalidTemperatureValue" time="0.000"/>
@@ -209,13 +215,13 @@ In mapping a Ceedling test suite to JUnit convetions, a Ceedling _test file_ bec
 </testsuites>
 ```
 
-## CppUnit XML Format
+### CppUnit XML Format
 
 [CppUnit] is an xUnit-style port of the JUnit framework to C/C++. Documentation for its XML test report is scattered and not easily linked.
 
 [CppUnit]: https://freedesktop.org/wiki/Software/cppunit/
 
-### Example CppUnit configuration YAML
+#### Example CppUnit configuration YAML
 
 ```yaml
 :plugins:
@@ -231,7 +237,7 @@ In mapping a Ceedling test suite to JUnit convetions, a Ceedling _test file_ bec
     :filename: cppunit_tests_report.xml
 ```
 
-### Example CppUnit test report
+#### Example CppUnit test report
 
 In the following example a single test file _TestUsartModel.c_ exercised four test cases. Two test cases passed, one test case failed, and one test case was ignored.
 
@@ -243,7 +249,7 @@ In mapping a Ceedling test suite to CppUnit convetions, a CppUnit test name is t
 
 ```xml
 <?xml version="1.0" encoding="utf-8" ?>
-<TestRun>
+<TestRun name="Ceedling Test Suite">
   <FailedTests>
     <Test id="1">
       <Name>test/TestUsartModel.c::testGetFormattedTemperatureFormatsTemperatureFromCalculatorAppropriately</Name>
@@ -278,11 +284,11 @@ In mapping a Ceedling test suite to CppUnit convetions, a CppUnit test name is t
 </TestRun>
 ```
 
-## HTML Format
+### HTML Format
 
 This plugin creates an adhoc HTML page in a single file.
 
-### Example HTML configuration YAML
+#### Example HTML configuration YAML
 
 ```yaml
 :plugins:
@@ -298,11 +304,11 @@ This plugin creates an adhoc HTML page in a single file.
     :filename: tests_report.html
 ```
 
-### Example HTML test report
+#### Example HTML test report
 
 ![](sample_html_report.png)
 
-# Creating Your Own Custom Report
+## Creating a Custom Report
 
 Creating your own report requires three steps:
 
@@ -310,7 +316,7 @@ Creating your own report requires three steps:
 1. Create a Ruby file in the directory from (1) per instructions that follow.
 1. Enable your new report in your `:report_tests_log_factory` Ceedling configuration.
 
-## Custom report configuration
+### Custom report configuration
 
 Configuration steps, (1) and (3) above, are documented by example below. Conventions simplify the Ruby programming and require certain naming rules that extend into your project configuration.
 
@@ -326,7 +332,7 @@ Configuration steps, (1) and (3) above, are documented by example below. Convent
     - fancy_shmancy         # Your custom report must follow naming rules (below)
 ```
 
-## Custom `TestsReporter` Ruby code
+### Custom `TestsReporter` code
 
 To create a custom report, here's what you gotta do:
 
@@ -334,16 +340,16 @@ To create a custom report, here's what you gotta do:
 1. The Ruby code itself must subclass an existing plugin class, `TestsReporter`.
 1. Your new subclass must be named `<CustomReport>TestsReporter` where `<CustomReport>` is the camelcase version of your report name from (1).
 1. Fill out up to four methods in your custom `TestsReporter` subclass:
-   * `setup()`
-   * `header()` (optional)
-   * `body()`
-   * `footer()` (optional)
+    * `setup()`
+    * `header()` (optional)
+    * `body()`
+    * `footer()` (optional)
 
 Overriding the default filename of your custom report happens just as it does for the built-in reports. In fact, apart from the custom load path, the built-in reports documented above use the same mechanisms as a custom report. These Ruby files can and should be used as references.
 
 You may access `:report_tests_log_factory` configuration for your custom report using a handy utility method documented in a later section.
 
-### Sample `TestReporter` custom subclass
+#### Sample `TestReporter` custom subclass
 
 The following code creates a simple, dummy report of the _FancyShmancy_ variety (note the name correspondence to the example configuration YAML above).
 
@@ -404,17 +410,17 @@ class FancyShmancyTestsReporter < TestsReporter
 end
 ```
 
-### Plugin hooks & test results data structure
+#### Plugin hooks & test results data structure
 
 See [_PluginDevelopmentGuide_][custom-plugins] for documentation of the test results data structure (i.e. the `results` method arguments in above sample code).
 
 See this plugin's built-in `TestsReports` subclasses — `json_tests_reporter.rb`, `junit_tests_reporter.rb`, and `cppunit_tests_reporter.rb` — for examples of using test results.
 
-[custom-plugins]: ../docs/PluginDevelopmentGuide.md
+[custom-plugins]: ../development/plugins/index.md
 
-### `TestsReporter` utility methods
+#### `TestsReporter` utility methods
 
-#### Configuration access: `fetch_config_value(*keys)`
+##### Configuration access: `fetch_config_value(*keys)`
 
 You may call the private method `fetch_config_value(*keys)` of the parent class `TestReporters` from your custom subclass to retrieve configuration entries.
 
@@ -422,7 +428,7 @@ This method automatically indexes into `:report_tests_log_factory` configuration
 
 `fetch_config_value(*keys)` expects a list of keys and only accesses configuration beneath `:report_tests_log_factory` ↳ `:<custom_report>`.
 
-##### Example _FancyShmancy_ configuration + `TestsReporter.fetch_config_value()` calls
+###### Example _FancyShmancy_ configuration + `TestsReporter.fetch_config_value()` calls
 
 ```yaml
 report_tests_log_factory:
@@ -444,3 +450,5 @@ fetch_config_value( :standardize, :filters ) => ['/^Foo/', '/Bar$/']
 
 fetch_config_value( :does, :not, :exist ) => nil
 ```
+
+<br/><br/>

data/{plugins/report_tests_pretty_stdout/README.md → docs/mkdocs/plugins/report-tests-pretty-stdout.md}

@@ -1,15 +1,15 @@
-# Ceedling Plugin: Pretty Test Suite Console Report
+# Pretty Test Suite Console Report
 
 Prints to the console ($stdout) simple, readable test suite results.
 
-# Plugin Overview
+## Plugin Overview
 
 This plugin is intended to be the default option for formatting a test suite's
 results when displayed at the console. It collects raw test results from the 
 individual test executables of your test suite and presents them in a more 
 readable summary form.
 
-# Setup
+## Setup
 
 Enable the plugin in your project.yml by adding `report_tests_pretty_stdout` to 
 the list of enabled plugins instead of any other `report_tests_*_stdout` 
@@ -21,11 +21,11 @@ plugin.
     - report_tests_pretty_stdout
 ```
 
-# Configuration
+## Configuration
 
 No additional configuration is needed once the plugin is enabled.
 
-# Example Output
+## Example Output
 
 ```sh
  > ceedling test:Model
@@ -50,5 +50,7 @@ IGNORED: 0
 ---------------------
 BUILD FAILURE SUMMARY
 ---------------------
-Unit test failures.
+ • Unit test failures.
 ```
+
+<br/><br/>

data/{plugins/report_tests_raw_output_log/README.md → docs/mkdocs/plugins/report-tests-raw-output-log.md}

@@ -1,9 +1,9 @@
-# Ceedling Plugin: Raw Test Output Logs
+# Raw Test Output Logs
 
 Capture extra console output — typically `printf()`-style statements — from 
 test cases to log files.
 
-# Plugin Overview
+## Plugin Overview
 
 This plugin gathers and filters console output from test executables into log 
 files. Though not required, it is usually used in addition to the 
@@ -14,7 +14,7 @@ Debugging in unit tested code is often accomplished with simple `printf()`-
 style calls to dump information to the console. This plugin's log files can be 
 helpful in supporting debugging efforts or quality validation.
 
-## Test executable output
+### Test executable output
 
 Ceedling and Unity cooperate to extract console statements from test executable
 runs. Unity-based test executables print test case pass/fail status messages
@@ -25,7 +25,7 @@ output, to format it and present summaries at the console.
 
 This plugin captures the unrecognized output to log files.
 
-## Log files
+### Log files
 
 Log files are only created if test executables produce console output apart from
 expected Unity test results as described above. Log files are named for the
@@ -35,7 +35,7 @@ Builds are differentiated by build context — `test`, `release`, or
 plugin-modified build (e.g. `gcov`). Log files are written to `<build
 root>/artifacts/<context>/<test file>.raw.log`.
 
-# Setup
+## Setup
 
 Enable the plugin in your Ceedling project:
 
@@ -45,6 +45,8 @@ Enable the plugin in your Ceedling project:
     - report_tests_raw_output_log
 ```
 
-# Configuration
+## Configuration
 
-No additional configuration is needed once the plugin is enabled.
+No additional configuration is needed once the plugin is enabled.
+
+<br/><br/>

data/{plugins/report_tests_teamcity_stdout/README.md → docs/mkdocs/plugins/report-tests-teamcity-stdout.md}

@@ -1,8 +1,8 @@
-# Ceedling Plugin: TeamCity Test Suite Console Report
+# TeamCity Test Suite Console Report
 
 Prints to the console ($stdout) test suite build events and results in a format understood by the CI product TeamCity.
 
-# Plugin Overview
+## Plugin Overview
 
 This plugin is intended to be used within [TeamCity] Continuous Integration
 (CI) builds. It processes Ceedling test suites and executable output into
@@ -18,7 +18,7 @@ options on enabling the build in CI but disabling it locally.
 [service-messages]:
 https://www.jetbrains.com/help/teamcity/service-messages.html
 
-# Setup
+## Setup
 
 Enable the plugin in your Ceedling project file by adding 
 `report_tests_teamcity_stdout`.
@@ -29,7 +29,7 @@ Enable the plugin in your Ceedling project file by adding
     - report_tests_teamcity_stdout
 ```
 
-# Configuration
+## Configuration
 
 All the `report_tests_*_stdout` plugins may be enabled in various combinations.
 But, some combinations may not make a great deal of sense. The TeamCity
@@ -53,14 +53,14 @@ Ceedling provides Mixins for applying configurations settings on top of your
 base project configuraiton file. 
 See the [Mixins documentation][ceedling-mixins] for full details.
 
-[ceedling-mixins]: ../docs/CeedlingPacket.md#base-project-configuration-file-mixins-section-entries
+[ceedling-mixins]: ../configuration/mixins.md#base-configuration-mixins-entries
 
 As an example, you might enable the plugin in the main project file that is
 committed to your repository while disabling the plugin in your local user
 project file that is ignored by your repository. In this way, the plugin would
 run on a TeamCity build server but not in your local development environment.
 
-# Example Output
+## Example Output
 
 TeamCity's convention for identifying tests uses the naming convention of the
 underlying Java language in which TeamCity is written,
@@ -92,3 +92,5 @@ This plugin maps Ceedling conventions to TeamCity test service messages as
 ##teamcity[testIgnored name='test.test/TestUsartModel.testShouldReturnWakeupMessage' flowId='15']
 ##teamcity[testSuiteFinished name='TestUsartModel' flowId='15']
 ```
+
+<br/><br/>

data/docs/mkdocs/plugins/valgrind.md

@@ -0,0 +1,192 @@
+# Valgrind
+
+Adds Ceedling tasks to run test executables under [Valgrind] memory error
+detection to help find memory leaks, invalid memory accesses, and
+use-after-free bugs in your C code.
+
+## Plugin overview
+
+!!! note "Linux only"
+    Valgrind runs on Linux and other Unix-like systems. It is not available
+    on Windows or macOS (ARM).
+
+The Valgrind plugin integrates [Valgrind] dynamic analysis into Ceedling,
+building and then running test executables under Valgrind’s Memcheck tool.
+
+The plugin provides two invocation modes mirroring standard `test:` tasks.
+
+- **Whole test suite**: By running `ceedling valgrind:all`, all test
+  executables are built and then each is run under Valgrind. A separate log
+  file is produced for each test executable in `build/artifacts/valgrind/`.
+- **Single test file**: By running `ceedling valgrind:<filename>`, a single
+  test executable is built and run under Valgrind, producing one log file.
+
+The plugin triggers standard `test` task builds but hands each test fixture
+executable off to Valgrind along with configurable arguments.
+
+By default the build runs all test binaries to completion and is marked as
+failed if any Valgrind memory errors are found. The optional `:fail_build:`
+setting can be set to `false` to log errors without failing the build.
+
+## Installation & set up
+
+### Installation
+
+You have at least 3 options for getting the `valgrind` tool working on your
+system, including one readymade option.
+
+#### Linux package manager
+
+Install Valgrind from your Linux distribution’s package manager:
+
+```shell
+sudo apt-get install valgrind   # Debian / Ubuntu
+sudo dnf install valgrind       # Fedora / RHEL
+```
+
+#### Build from source
+
+Or build from source from [valgrind.org/downloads/](https://valgrind.org/downloads/).
+
+#### _MadScienceLab_ Docker images
+
+Fully packaged [_MadScienceLab_ Docker images][docker-hub] containing Ruby, 
+Ceedling, the GCC toolchain, and more are available. The `-plugins` variants 
+of the images come with all of Ceedling’s plugin tools preinstalled.
+
+[docker-hub]: https://hub.docker.com/repository/docker/throwtheswitch/
+
+### Enable the plugin
+
+Enable the plugin by adding `valgrind` to the enabled plugins list in your
+project configuration:
+
+```yaml
+:plugins:
+  :enabled:
+    - valgrind
+```
+
+## Configuration
+
+The plugin ships with sensible defaults that enable full leak checking. By
+default the build runs all test binaries to completion and is marked as failed
+if any memory errors are found. Set `:fail_build: false` to log errors without
+failing the build.
+
+You can change the Valgrind configuration in your project configuration 
+under an optional `:valgrind` section.
+
+### Default configuration
+
+In the default configuration, the Valgrind plugin will run the entire test 
+suite, collecting Valgrind reports for each test fixture executable.
+
+By default, the plugin runs with these command line arguments for `valgrind`:
+
+- `--leak-check=full`
+- `--show-leak-kinds=all`
+- `--track-origins=yes`
+- `--errors-for-leak-kinds=all`
+
+### `:arguments:`
+
+The list of flags passed to Valgrind for every test binary. To override the
+defaults, redefine the argument list in your project configuration:
+
+```yaml
+:valgrind:
+  :arguments:
+    # A subset of the default arguments
+    - "--leak-check=full"
+    - "--show-leak-kinds=all"
+```
+
+### `:fail_build:`
+
+When `true` (the default), any memory errors are logged immediately after 
+running a test executable. After all test binaries complete execution, if 
+any memory errors were found across the run, the build is marked as failed 
+with a total count of memory errors and test files processed.
+
+When `false`, memory errors are still logged per test binary but the build is
+not marked as failed.
+
+```yaml
+:valgrind:
+  :fail_build: false
+```
+
+!!! note "Detection uses log parsing, not Valgrind’s exit code"
+    Valgrind’s `--error-exitcode` flag is not used because its exit code would
+    overlap with Unity’s own exit code, which equals the number of failing test
+    cases. Instead, the plugin parses the `ERROR SUMMARY: N errors` line written
+    to the Valgrind log file.
+
+## Usage
+
+The Valgrind plugin follows the conventions of `test:` tasks.
+
+### Run Valgrind for all tests
+
+Build all test executables and run each under Valgrind:
+
+```shell
+$ ceedling valgrind:all
+```
+
+### Run Valgrind for a single test file
+
+Build and run Valgrind for one test file (pass the filename, no path):
+
+```shell
+$ ceedling valgrind:test_my_module.c
+```
+
+You can also pass just the source filename; Ceedling will locate the
+corresponding test file automatically:
+
+```shell
+$ ceedling valgrind:my_module.c
+```
+
+## Artifacts
+
+Each test executable produces a Valgrind log file at:
+
+```
+build/artifacts/valgrind/<test_name>.log
+```
+
+For example, running `ceedling valgrind:test_my_module.c` produces:
+
+```
+build/artifacts/valgrind/test_my_module.log
+```
+
+These log files contain the full Valgrind Memcheck output, including any
+detected memory errors, leak summaries, and (with `--track-origins=yes`)
+the origin of uninitialized values.
+
+The log files are included in `ceedling clean` targets.
+
+## Interpreting results
+
+To review the log for a specific test:
+
+```shell
+cat build/artifacts/valgrind/test_my_module.log
+```
+
+Common Valgrind findings include:
+
+| Finding | Description |
+|---------|-------------|
+| `definitely lost` | Memory was allocated but never freed — a confirmed leak |
+| `indirectly lost` | Memory reachable only through another leaked block |
+| `Invalid read/write` | Access outside allocated memory bounds |
+| `Use of uninitialised value` | Reading memory before it was written |
+
+See [Valgrind] documentation for more details.
+
+[Valgrind]: https://valgrind.org

data/docs/mkdocs/project/release-history.md

@@ -0,0 +1,61 @@
+# Release History
+
+## Versioned Release Artifacts
+Ceedling releases are available as:
+
+* [Repository build artifacts](https://github.com/ThrowTheSwitch/Ceedling/releases) (downloadable 
+  Ruby .gem files).
+* [Ruby gems](https://rubygems.org/gems/ceedling) for installation from the RubyGems registry by 
+  the `gem` command line tool.
+* [Docker images](https://hub.docker.com/r/throwtheswitch/madsciencelab) with the `ceedling` tool 
+  ready to run from the command line.
+
+Ceedling is known to be compatible with Ruby 3.0 – 3.4. It is ready for use with Ruby 3.5 but has 
+had little real world use with Ruby 3.5.
+
+## History
+
+Ceedling’s release history is documented in four files that live in the
+repository and follow [keepachangelog.com](https://keepachangelog.com/en/1.0.0/)
+conventions. These documents span the cumulative project history and are
+maintained standalone rather than versioned with this documentation.
+
+<div class="grid cards" markdown>
+
+-   :material-bullhorn-outline: **[Release Notes][release-notes]**
+
+    ---
+
+    Detailed [release notes][release-notes] for announcements, education, and acknowledgements. 
+    This is the primary reference for quickly understanding what changed between versions.
+
+-   :material-history: **[Changelog][changelog]**
+
+    ---
+
+    A detailed, chronological log of [all changes][changelog] — additions, fixes, changes, and
+    anything removed.
+
+-   :material-alert-octagon-outline: **[Breaking Changes][breaking-changes]**
+
+    ---
+
+    A focused list of [breaking changes][breaking-changes] across releases. Consult this document
+    when upgrading to understand what in your project configuration or test
+    code may need to be updated.
+
+-   :material-bug-outline: **[Known Issues][known-issues]**
+
+    ---
+
+    A high-level list of [presently known problems][known-issues] and limitations for each
+    release.
+
+</div>
+
+[release-notes]: https://github.com/ThrowTheSwitch/Ceedling/blob/master/docs/ReleaseNotes.md
+[breaking-changes]: https://github.com/ThrowTheSwitch/Ceedling/blob/master/docs/BreakingChanges.md
+[changelog]: https://github.com/ThrowTheSwitch/Ceedling/blob/master/docs/Changelog.md
+[known-issues]: https://github.com/ThrowTheSwitch/Ceedling/blob/master/docs/KnownIssues.md
+
+<br/><br/>