The instructions given in both: Contributing and Contributing Guide (and I agree we don't need both; just one for development setup guidance), are fine as far as they go. However, they do not cover how to setup a development environment when working on multiple issues. This led me originally to create a clone per issue, so I could follow the instructions without understanding exactly the underlying technology. However, several developers have told me a clone per issue is a bad idea. One problem is it is storage space expensive to run nox and running nox on separate clones on the same machine could take up a lot of disk space.

So, how do you setup a single clone to work on multiple issues. There are several problems. How do you avoid constantly doing git checkouts as you move between the issues. One idea, discussed here : A quick question on Discord is to use worktrees. That allows the developer to keep branches of the common clone in separate directories. However there are other problems. For example, where do you put the configuration files for the master, minion and pki material for each issue. You can't store them in /local/etc/salt, as recommended by the contributing instructions, since each issue potentially needs its own configuration files. When you navigate to the worktree directory for a specific issue, the configuration data in /local/etc/salt doesn't change. If you commit the configuration data per branch so it shows up when you switch worktrees, then when you eventually push the branch to the developer's GitHub repo, you will have a commit that shouldn't be there, which will be a problem when you submit a PR.

Another similar problem is where do you put pillar or file data for a particular issue? You can't use /srv/pillar or /srv/salt, since they are common across all issue branches within the clone. You can use pillar_roots and file_roots to define on a per branch basis where to find this data, but this runs into the same problem as storing per branch configuration data. One suggestion made by @gou177 is to use the git feature of .git/info/exclude to identify files and directories that should not be tracked by git. This would allow the retention of a directory for per branch config data, pillar and file data that would not be tracked by git (e.g., instead of putting local/etc/salt in the git source directory, create a directory in the git source directory called, say, untracked and beneath it directories for each branch. Beneath those directories, you could then put the particular branch local/etc/salt, pillar and file data.

Whether this is the best way to organize things is an open issue. What this comment attempts to identify is the Contributing instructions should explain how to organize a development environment that is suitable for working on multiple issues.

I experimented using an untracked directory in the clone directory tree. This doesn't work, since the worktrees do not implement a mirror of the base repo (see: Discord discussion). Thus, the untracked directory does not appear in the worktree branch directories. Another possibility is to keep configuration data for each branch in a directory structure that is external to the clone directory tree. I am experimenting with this idea at present.

Using a directory structure external to the clone directory works. See: External Directory. However, there is the question of how to do this on Windows and Macs. I am pretty sure the same strategy should work on a Mac, since it is based on NetBSD. However, I have little experience using Windows, so that is an open question.

Another potential problem with this approach is when executing salt scripts (like salt-master, salt-minion, salt-key and salt), the specification of the configuration file pathname is long and requires the developer to remember which worktree is current. For example, if working in a worktree called "bugfix-65265" and assuming the minion id is "bugfix-65265" and the configuration file associated with this worktree is also "bugfix-65265", the script execution from the scripts directory is:

(salt) dan@Eclipse-salt:~/salt-worktrees/bugfix-65265/scripts$ salt --config-dir=../../../salt-config/bugfix-65265/local/etc/salt/ 'bugfix-65265' test.ping

This imposes a lot of typing on the developer and remembering what issue is under test when executing scripts. There may be a way to create a bash script that loads an environment variable with the config directory pathname based on the pathname of the worktree, providing a way to simply set this variable by executing it. But, again, that works for *nix based OSes, but I don't know what to do in the case of Windows.

How to handle Windows is an important question, since the "Salt Contributing" write-up must suggest a way of multi-issue development for not only Linux and Mac, but also Windows.