docs: improve migration guide

KyleKing · Aug 14, 2024 · a3aaebb · a3aaebb
1 parent 02ee759
commit a3aaebb
Show file tree

Hide file tree

Showing 4 changed files with 64 additions and 15 deletions.
diff --git a/docs/docs/CHANGELOG.md b/docs/docs/CHANGELOG.md
@@ -2,6 +2,20 @@
 
 ### Fix
 
+- handle when dev-dependencies are missing
+- minimize calcipy extras when testing in nox
+- handle git, path, and other complex versions for sync task
+- pinning urllib3 for Python 3.11 wasn't necessary
+
+### Refactor
+
+- minor logging improvements for pack.sync
+
+## 4.0.0 (2024-07-06)
+
+### Fix
+
+- add timeout to httpx requests
 - don't sync versions when a maximum version is specified
 - prevent installing urllib3 in Python 3.10
 - add missing pylint extra

diff --git a/docs/docs/CODE_TAG_SUMMARY.md b/docs/docs/CODE_TAG_SUMMARY.md
@@ -1,12 +1,13 @@
 # Collected Code Tags
 
-| Type | Comment                                                                                            | Last Edit  | Source File                                                                                                                                                                                                                  |
-|------|----------------------------------------------------------------------------------------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| TODO | Add unit test                                                                                      | 2024-07-06 | [calcipy/tasks/pack.py:57](https://github.com/KyleKing/calcipy/blame/e45ecadfa5b994d9c0a2a47138fa0e083261e3eb/calcipy/tasks/pack.py#L57)                                                                                     |
-| TODO | Add unit test                                                                                      | 2024-07-06 | [calcipy/tasks/pack.py:91](https://github.com/KyleKing/calcipy/blame/e45ecadfa5b994d9c0a2a47138fa0e083261e3eb/calcipy/tasks/pack.py#L91)                                                                                     |
-| TODO | Look into running tasks from within other tasks to support '--continue' and more readable logs --> | 2023-02-19 | [docs/docs/MIGRATION.md:112](https://github.com/KyleKing/calcipy/blame/d95eb85ab7f6d45459ed7b3ff2dc99ae3c92fa61/docs/docs/MIGRATION.md#L42)                                                                                  |
-| TODO | Capture logging output and check...                                                                | 2023-02-19 | [tests/check_for_stale_packages/test_check_for_stale_packages.py:64](https://github.com/KyleKing/calcipy/blame/a8b69e7b04d9b15eabff8897f2de7703898c2afc/tests/check_for_stale_packages/test_check_for_stale_packages.py#L63) |
-| TODO | Capture logging output and check...                                                                | 2023-02-19 | [tests/check_for_stale_packages/test_check_for_stale_packages.py:88](https://github.com/KyleKing/calcipy/blame/3f42ad855eb7024ff48af35d496633a87d4a14ac/tests/check_for_stale_packages/test_check_for_stale_packages.py#L26) |
+| Type | Comment                             | Last Edit  | Source File                                                                                                                                                                                                                  |
+|------|-------------------------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| TODO | How to capture output?              | 2024-08-14 | [calcipy/collection.py:38](https://github.com/KyleKing/calcipy/blame/main
+/calcipy/collection.py#L38)                                                                                                                        |
+| TODO | Add unit test                       | 2024-07-06 | [calcipy/tasks/pack.py:57](https://github.com/KyleKing/calcipy/blame/e45ecadfa5b994d9c0a2a47138fa0e083261e3eb/calcipy/tasks/pack.py#L57)                                                                                     |
+| TODO | Add unit test                       | 2024-07-06 | [calcipy/tasks/pack.py:91](https://github.com/KyleKing/calcipy/blame/e45ecadfa5b994d9c0a2a47138fa0e083261e3eb/calcipy/tasks/pack.py#L91)                                                                                     |
+| TODO | Capture logging output and check... | 2023-02-19 | [tests/check_for_stale_packages/test_check_for_stale_packages.py:64](https://github.com/KyleKing/calcipy/blame/a8b69e7b04d9b15eabff8897f2de7703898c2afc/tests/check_for_stale_packages/test_check_for_stale_packages.py#L63) |
+| TODO | Capture logging output and check... | 2023-02-19 | [tests/check_for_stale_packages/test_check_for_stale_packages.py:88](https://github.com/KyleKing/calcipy/blame/3f42ad855eb7024ff48af35d496633a87d4a14ac/tests/check_for_stale_packages/test_check_for_stale_packages.py#L26) |
 
 Found code tags for TODO (5)
 

diff --git a/docs/docs/DEVELOPER_GUIDE.md b/docs/docs/DEVELOPER_GUIDE.md
@@ -55,20 +55,20 @@ poetry config pypi-token.pypi ...
 | `calcipy/check_for_stale_packages/_check_for_stale_packages.py` | 126        | 13      | 3        | 86.7%    |
 | `calcipy/cli.py`                                                | 34         | 1       | 75       | 92.9%    |
 | `calcipy/code_tag_collector/__init__.py`                        | 5          | 2       | 0        | 60.0%    |
-| `calcipy/code_tag_collector/_collector.py`                      | 129        | 2       | 0        | 96.6%    |
+| `calcipy/code_tag_collector/_collector.py`                      | 129        | 1       | 0        | 98.3%    |
 | `calcipy/collection.py`                                         | 33         | 0       | 52       | 97.5%    |
 | `calcipy/dot_dict/__init__.py`                                  | 5          | 2       | 0        | 60.0%    |
 | `calcipy/dot_dict/_dot_dict.py`                                 | 6          | 0       | 0        | 100.0%   |
 | `calcipy/experiments/__init__.py`                               | 0          | 0       | 0        | 100.0%   |
 | `calcipy/experiments/bump_programmatically.py`                  | 22         | 22      | 0        | 0.0%     |
 | `calcipy/experiments/check_duplicate_test_names.py`             | 33         | 0       | 2        | 98.2%    |
-| `calcipy/experiments/sync_package_dependencies.py`              | 40         | 40      | 0        | 0.0%     |
+| `calcipy/experiments/sync_package_dependencies.py`              | 46         | 46      | 0        | 0.0%     |
 | `calcipy/file_search.py`                                        | 32         | 0       | 2        | 100.0%   |
 | `calcipy/invoke_helpers.py`                                     | 27         | 4       | 0        | 83.8%    |
 | `calcipy/md_writer/__init__.py`                                 | 5          | 2       | 0        | 60.0%    |
 | `calcipy/md_writer/_writer.py`                                  | 91         | 6       | 0        | 89.6%    |
 | `calcipy/noxfile/__init__.py`                                   | 5          | 2       | 0        | 60.0%    |
-| `calcipy/noxfile/_noxfile.py`                                   | 38         | 2       | 50       | 91.3%    |
+| `calcipy/noxfile/_noxfile.py`                                   | 39         | 2       | 51       | 91.5%    |
 | `calcipy/scripts.py`                                            | 5          | 0       | 37       | 100.0%   |
 | `calcipy/tasks/__init__.py`                                     | 0          | 0       | 0        | 100.0%   |
 | `calcipy/tasks/all_tasks.py`                                    | 46         | 0       | 0        | 94.8%    |
@@ -83,7 +83,7 @@ poetry config pypi-token.pypi ...
 | `calcipy/tasks/tags.py`                                         | 18         | 1       | 0        | 90.9%    |
 | `calcipy/tasks/test.py`                                         | 43         | 1       | 2        | 90.2%    |
 | `calcipy/tasks/types.py`                                        | 11         | 0       | 0        | 93.3%    |
-| **Totals**                                                      | 1005       | 122     | 259      | 84.0%    |
+| **Totals**                                                      | 1012       | 127     | 260      | 83.6%    |
 
-Generated on: 2024-07-06
+Generated on: 2024-08-13
 <!-- {cte} -->
diff --git a/docs/docs/MIGRATION.md b/docs/docs/MIGRATION.md
@@ -1,6 +1,31 @@
 # Migration Guide
 
-## `calcipy 1.0.0`
+## `v4`
+
+The total number of dependencies was reduce even further by replacing flake8, isort, and other tooling with ruff; fewer mkdocs plugins; and fewer steps in the `main` run task to speed up normal usage.
+
+The only breaking [change impacted `recipes`](https://github.com/KyleKing/recipes/commit/b3fcf8136af77ccf1bd3ee1fb4297b79dd7e86ea#diff-4bf564fcd9dbaec9e9807f16f649791c1e333f89db8160ad715d3c0c09a1a65c) when `write_autoformatted_md_sections` was renamed to `write_template_formatted_md_sections`.
+
+### Speed Test
+
+Following up on performance checks from the `v2` migration. The performance is comparable, but you will see savings in cache size and poetry install and when running `main` (`./run main` for Calcipy, currently takes ~20s)
+
+```sh
+> hyperfine -m 20 --warmup 5 ./run
+Benchmark 1: ./run
+Time (mean ± σ):     863.9 ms ±  10.0 ms    [User: 550.7 ms, System: 102.3 ms]
+Range (min … max):   848.5 ms … 885.3 ms    20 runs
+> hyperfine -m 20 --warmup 5 "poetry run calcipy-tags"
+Benchmark 1: poetry run calcipy-tags
+Time (mean ± σ):     770.5 ms ±   5.7 ms    [User: 470.6 ms, System: 89.5 ms]
+Range (min … max):   760.1 ms … 780.3 ms    20 runs
+```
+
+## `v3`
+
+Replaced features from flake8 and plugins with corresponding checks from ruff, however both are still used in parallel.
+
+## `v2`
 
 ### Background
 
@@ -22,6 +47,17 @@ While refactoring, the global configuration was mostly removed (`DoitGlobals`) a
 
 It turns out that switching to `invoke` appears to have only saved 100ms
 
+```sh
+> hyperfine -m 20 --warmup 5 ./run
+Benchmark 1: ./run
+Time (mean ± σ):     863.9 ms ±  10.0 ms    [User: 550.7 ms, System: 102.3 ms]
+Range (min … max):   848.5 ms … 885.3 ms    20 runs
+> hyperfine -m 20 --warmup 5 "poetry run calcipy-tags"
+Benchmark 1: poetry run calcipy-tags
+Time (mean ± σ):     770.5 ms ±   5.7 ms    [User: 470.6 ms, System: 89.5 ms]
+Range (min … max):   760.1 ms … 780.3 ms    20 runs
+```
+
 ```sh
 > hyperfine -m 20 --warmup 5 "poetry run python -c 'print(1)'"
 Benchmark 1: poetry run python -c 'print(1)'
@@ -109,8 +145,6 @@ SUM:                             7             37             15             71
 
 ### doit output
 
-<!-- TODO: Look into running tasks from within other tasks to support '--continue' and more readable logs -->
-
 I would like to restore the `doit` task summary, but `invoke`'s architecture doesn't really make this possible. The `--continue` option was extremely useful, but that also might not be achievable.
 
 ```sh