From 24de73fba5bbb8a93d4fefeaae4074d9299cb553 Mon Sep 17 00:00:00 2001 From: jeanluc Date: Mon, 25 Nov 2024 12:39:47 +0100 Subject: [PATCH] Misc docs fixes and additions --- docs/ref/concepts.md | 2 +- docs/topics/creation.md | 2 +- docs/topics/extraction.md | 37 ++++++++++++++++++++++++++++++++-- docs/topics/installation.md | 17 ++++++++++++++-- docs/topics/publishing.md | 7 ++++++- docs/topics/testing/writing.md | 37 ++++++++++++++++++++++++++++++++++ 6 files changed, 95 insertions(+), 7 deletions(-) diff --git a/docs/ref/concepts.md b/docs/ref/concepts.md index e892526..4649c0c 100644 --- a/docs/ref/concepts.md +++ b/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. diff --git a/docs/topics/creation.md b/docs/topics/creation.md index 95f3fa4..e8c2a67 100644 --- a/docs/topics/creation.md +++ b/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]' ``` diff --git a/docs/topics/extraction.md b/docs/topics/extraction.md index d0ae3a9..2bb3c73 100644 --- a/docs/topics/extraction.md +++ b/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 diff --git a/docs/topics/installation.md b/docs/topics/installation.md index 1ee011f..a80a9cd 100644 --- a/docs/topics/installation.md +++ b/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/ diff --git a/docs/topics/publishing.md b/docs/topics/publishing.md index 797107a..be3ecdc 100644 --- a/docs/topics/publishing.md +++ b/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: diff --git a/docs/topics/testing/writing.md b/docs/topics/testing/writing.md index 1a39eff..1f20678 100644 --- a/docs/topics/testing/writing.md +++ b/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 ` (or {py:func}`state.show_sls `) them and assert against the {py:class}`return `: + +```{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 ` to the functional test minion's state directory. ### Integration tests