Misc docs fixes and additions

docs/ref/concepts.md

@@ -39,7 +39,7 @@ This drastic change is driven by several key goals:
 The migration splits modules into three categories:
 
 1. **Core modules**: These will remain within the Salt codebase and follow the Salt release cycle.
-2. **Supported modules (extended core)**: These modules will move to their own repositories within the `saltstack` GitHub organization, where they can be maintained separately.
+2. **Supported modules (extended core)**: These modules will move to their own repositories within the `salt-extensions` GitHub organization, where they can be maintained separately by core maintainers.
 (community-modules-target)=
 3. **Community Modules**: These will be removed from the Salt Core codebase. Community members can take over their maintenance, either in the community-run Salt Extensions GitHub organization or in their own repositories.
 

docs/topics/creation.md

@@ -76,7 +76,7 @@ To create the virtualenv, it is recommended to use the same Python version (MAJO
 
 ```bash
 python3.10 -m venv .venv
-source venv/bin/activate
+source .venv/bin/activate
 python -m pip install -e '.[tests,dev,docs]'
 ```
 

docs/topics/extraction.md

@@ -12,6 +12,12 @@ Ensure you always use the latest HEAD of `saltext-migrate` to avoid incompatibil
 When encountering a bug, first try to update the tool.
 :::
 
+:::{tab} uv
+```bash
+uv tool install git-filter-repo
+uv tool install git+https://github.com/salt-extensions/salt-extension-migrate
+```
+:::
 :::{tab} pipx
 ```bash
 pipx install git-filter-repo
@@ -47,7 +53,28 @@ The tool will:
 6. [Create a virtual environment](migration-venv-target) for your project
 7. [Apply rewrites](migration-clean-up-target) (with fixes and improvements versus `salt-rewrite`)
 8. Install and run pre-commit
-9. Provide an overview of issues to fix and next steps
+9. Provide an overview of [issues to fix](migrate-manual-fixes-target) and next steps.
+
+### Common issues
+#### Missing files
+If the default path filter does not pick up all related modules, you can override the names it searches for:
+
+```bash
+saltext-migrate zfs -m zfs -m zpool
+```
+
+If there are still missing paths, you can add them explicitly:
+
+```bash
+saltext-migrate zfs -m zfs -m zpool -i docs/foo/bar.rst
+```
+
+#### File renaming caused colliding pathnames!
+By default, `saltext-migrate` tries to keep file names the same. Since it needs to rewrite e.g. both `tests/pytests/unit/modules/test_foo.py` and `tests/unit/modules/test_foo.py` into `tests/unit/modules/test_foo.py`, some specific git histories can cause conflicts. You can workaround this by specifying `--avoid-collisions`:
+
+```bash
+saltext-migrate postgresql -m postgres --avoid-collisions
+```
 
 (manual-extraction-example)=
 ## A manual module extraction example
@@ -56,6 +83,11 @@ Below are some rough steps to extract an existing set of modules into an extensi
 
 ### 1. Install the Git history filtering tool
 
+:::{tab} uv
+```bash
+uv tool install git-filter-repo
+```
+:::
 :::{tab} pipx
 ```shell
 pipx install git-filter-repo
@@ -156,7 +188,7 @@ To create the virtualenv, it is recommended to use the same Python version (MAJO
 
 ```shell
 python3.10 -m venv .venv --prompt saltext-stalekey
-source venv/bin/activate
+source .venv/bin/activate
 ```
 
 Please ensure you're inside your virtual environment from here on.
@@ -233,6 +265,7 @@ from unittest.mock import MagicMock, Mock, patch
 
 The generated Salt extension project does not account for a `tests/pytests` subdirectory. Its contents need to be moved to the top-level `tests` directory.
 
+(migrate-manual-fixes-target)=
 ## Issues needing manual fixing
 (utils-dunder-into-saltext-utils)=
 ### `__utils__` into Salt extension utils

docs/topics/installation.md

@@ -4,9 +4,17 @@ To render the template, you only need a functional [Copier][copier-docs] install
 
 ## Copier
 
-:::{tab} pipx
+It’s recommended to install Copier globally using either [uv][uv-docs] or [pipx][pipx-docs]:
+
+:::{tab} uv
+
+
+```bash
+uv tool install --python 3.10 --with copier-templates-extensions 'copier>=9.3'
+```
+:::
 
-It’s recommended to install Copier globally using [pipx][pipx-docs]:
+:::{tab} pipx
 
 ```bash
 pipx install 'copier>=9.3' && \
@@ -23,6 +31,10 @@ python -m pip install 'copier>=9.3' copier-templates-extensions
 ```
 :::
 
+:::{note}
+The `copier` virtual environment should be based on the Python version (MAJOR.MINOR) [listed here](https://github.com/saltstack/salt/blob/master/cicd/shared-gh-workflows-context.yml), at the time of writing Python 3.10. Other versions - especially higher ones - should work, but the template's CI tests only verify the mentioned version.
+:::
+
 :::{important}
 This template includes custom Jinja extensions, so ensure that [copier-templates-extensions][copier-templates-extensions] is installed in the same environment as `copier`. The example commands above handle this.
 :::
@@ -31,3 +43,4 @@ This template includes custom Jinja extensions, so ensure that [copier-templates
 [copier-multiselect-pr]: https://github.com/copier-org/copier/pull/1386
 [copier-templates-extensions]: https://github.com/copier-org/copier-templates-extensions
 [pipx-docs]: https://pipx.pypa.io/stable/
+[uv-docs]: https://docs.astral.sh/uv/

docs/topics/publishing.md

@@ -81,13 +81,18 @@ git switch main && git fetch upstream && git rebase upstream/main
 Create a new tag named after the version:
 
 ```bash
-git tag v1.0.0
+git tag -s v1.0.0
 ```
 
 :::{important}
 The tag must start with `v` for the default publishing workflows to work correctly.
 :::
 
+:::{note}
+It's recommended to create annotated (`git tag -a`) or signed (`git tag -s`) tags
+since they create an immutable git object. Regular tags are just pointers to a specific commit.
+:::
+
 ### 4: Push the tag
 
 Push the new tag upstream to trigger the publishing workflow:

docs/topics/testing/writing.md

@@ -248,6 +248,37 @@ def test_state_module_test(states):
     assert ret.changes
 ```
 
+##### Testing modules in the state compiler context
+
+You can create test `sls` files, {py:func}`state.apply <salt.modules.state.apply_>` (or {py:func}`state.show_sls <salt.modules.state.show_sls>`) them and assert against the {py:class}`return <saltfactories.utils.functional.MultiStateResult>`:
+
+```{code-block} python
+import pytest
+from textwrap import dedent
+
+@pytest.fixture
+def foo_sls(state_tree):
+    sls = "test_foo"
+    contents = dedent(
+        """
+        {%- set name = salt["foo.bar"]() %}
+
+        Test foo state:
+          foo.bard:
+            - name: {{ name }}
+        """
+    ).strip()
+
+    with pytest.helpers.temp_file(f"{sls}.sls", contents, state_tree):
+        yield sls
+
+
+def test_foo_in_state_compiler(foo_sls, loaders):
+    ret = loaders.modules.state.apply(foo_sls)
+    assert not ret.failed
+    assert "foo" in ret.raw["foo_|-Test foo state_|-foo_|-bard"]["comment"]
+```
+
 #### Important fixtures
 
 ##### `loaders`
@@ -275,6 +306,12 @@ def test_state_module_test(states):
 *Description*
 :   Shortcut for `loaders.states`.
 
+##### `state_tree`
+*Scope*
+:   module
+
+*Description*
+:   The {py:class}`Path <pathlib.Path>` to the functional test minion's state directory.
 
 ### Integration tests