From 7b3373850b60ac09f4eaabf4e1b3a779ab539bbd Mon Sep 17 00:00:00 2001
From: Angelika Tyborska <angelika@bitcrowd.net>
Date: Fri, 22 Mar 2024 09:23:51 +0100
Subject: [PATCH] Extend version doc with new multi-version doctests

---
 docs/bitstyles_version_compatibility.md | 42 +++++++++++++++++++++----
 1 file changed, 36 insertions(+), 6 deletions(-)

diff --git a/docs/bitstyles_version_compatibility.md b/docs/bitstyles_version_compatibility.md
index 19a54e2..82743e7 100644
--- a/docs/bitstyles_version_compatibility.md
+++ b/docs/bitstyles_version_compatibility.md
@@ -7,13 +7,43 @@ General rules:
 
 ## Doctests ("stories")
 
-Component doctests (created with a custom `story` macro) describe components as their would render for the highest currently supported bitstyles version (default version).
+The `story` macro is used to generate doctests, as well as the component preview in docs.
 
-## Versions showcase
+The first argument is the story's description (`"An error tag"`), the second argument is an iex code snippet, and the third argument is the expected result when the code snippet gets executed. The third argument can be a single charlist, or a keyword lists that maps bitstyles version numbers to charlists. If the third argument is a single charlist, it's assumed that is the expected result for the default bitstyles version.
+
+⚠️ Note that the 4 space indentation in the code snippet and the expected result is important.
 
-Because doctests can only show how a bitstyles_phoenix component looks like with the default bitstyles versions, they can't be used to preview components with other bitstyles versions. 
+### Multi-version doctest example
+
+```elixir
+  story(
+    "An error tag",
+    '''
+        iex> assigns = %{}
+        ...> render ~H"""
+        ...> <.ui_error error={{"Foo error", []}} />
+        ...> """
+    ''',
+    "4.3.0": '''
+        """
+        <span class="u-fg-warning">
+          Foo error
+        </span>
+        """
+    ''',
+    "3.0.0": '''
+        """
+        <span class="u-fg--warning">
+          Foo error
+        </span>
+        """
+    '''
+  )
+```
+
+## Versions showcase
 
-A showcase of components in different versions can be generated by running:
+A showcase of components in all supported bitstyles versions can be generated by running:
 
 ```bash
 mix run scripts/generate_version_showcase.ex
@@ -40,9 +70,9 @@ open version_showcase/index.html
 5. Add the new version to the version lists in [`generate_version_showcase`](../scripts/generate_version_showcase.ex).
 6. Handle classes renamed by bitstyles by adding new clauses of the `classname/2` function in [`BitstylesPhoenix.Bitstyles`](../lib/bitstyles_phoenix/bitstyles.ex).
 7. If renaming classes is not enough to upgrade correctly, you can perform [a bitstyles version check in a component](#an-example-of-a-bitstyles-version-check-in-a-component).
-8. Run `mix test`. Fix all doctests until `mix test` succeeds.
+8. Run `mix test`. Fix all doctests until `mix test` succeeds. Add new expected values for the new version, and keep the current expected value for the previous version (see [multi-version doctest example](#multi-version-doctest-example))
 9. Run `mix docs` to preview components after making changes to them.
-10. Use the [versions showcase](#versions-showcase) to test that you didn't break for older bitstyles versions.
+10. Use the [versions showcase](#versions-showcase) to test that you didn't break anything for older bitstyles versions.
 
 ### An example of a bitstyles version check in a component