This repository is used to track and coordinate the migration of Salt modules to extensions.
Follow these steps to set up your development environment and migrate Salt modules to extensions.
First, install the salt-extension
tool by following the instructions in the salt-extension
repository.
Create an empty working directory and navigate into it:
mkdir working-dir
cd working-dir
Inside the working directory, create an empty directory to hold the extension migration files:
mkdir apache
cd apache
Use the create-salt-extension command to create a new Salt extension inside the extension migration directory. Replace the placeholders with your information:
create-salt-extension -A "Maintainer Name" \
-E "maintainer@example.com" \
-S "Salt Extension for interacting with Apache" \
-U "https://github.com/salt-extensions/saltext-apache" \
-L apache \
--dest saltext-apache \
apache
Note: The
-L apache
option sets the license of the extension to "Apache 2.0" and should not be changed when replacing placeholder text in the previous command. The otherapache
will be replaced with the name of the extension you are migrating.
Navigate into the extension directory and initialize it as a Git repository:
cd saltext-apache
git init --initial-branch=main
touch requirements/{changelog,dev,docs,docs-auto,lint,tests}.txt
pip install pre-commit # may not need to be done again if in a pre-existing virtual environment
pre-commit install
git add .
git commit -m "Initial commit of extension framework"
*You may need to
pip install
git-filter-repo
andpylint
. If you are using git < 2.28, theinitial-branch
option is not present andgit init
will default to the branch being "master" instead of "main". Note that you won't be able to change it withgit branch -m master main
until after your first commit.
Note: In case of failures due to pinned project dependencies, clean out build and artifacts like below, and try again.
sudo rm -rf ./build/*
sudo rm -rf ./artifacts/*
git add .
git commit -m "Initial commit of extension framework"
Follow these instructions to migrate Salt modules to extensions.
First, git clone this extension-migration to your local environment into a separate folder, not in your saltext-_____
(if it isn't already).
then, cd into the directory before saltext-_______ (example, the helm
directory instead of saltext-helm
)
To perform a dry run migration of modules that contain "apache" in their name from a branch called "filter-source" into an extension directory called "saltext-apache", use the following command:
extension-migrate.py --dry_run \
--file_filter apache \
--source_branch filter-source \
--extension_dir saltext-apache
Note that all the dry-run does is preprare the command and then echo it to the terminal. If you run the dry run, and then the actual migration, you may get a fatal error
complaining something already is created. This is not actaully a fatal error and can be safely ignored.
To perform the actual migration of modules, use the following command:
extension-migrate.py --file_filter apache \
--source_branch filter-source \
--extension_dir saltext-apache
If there are any merge conflicts, resolve them manually.
Merge the "filter-target" branch into the main branch:
git add .
git commit -m "Merging in modules from Salt"
git checkout main
git merge filter-target
Change any references of __utils__
to salt.utils
:
SALTEXT_NAME=apache salt-rewrite -F fix_saltext_utils_imports .
Finally, push the changes to the Salt extension's repository. Contact an Owner of the salt-extensions
organization to
obtain a repository for your Extension.