saltstack / saltstack/salt

Changes Return by a State

Open
#60,807 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

doc-request documentation severity-low time-estimate-sprint
Dominant language
Python
Stars
15.7k
Forks
5.6k
Avg merge
2d 44m
Merged PRs (30d)
80

Description

Description
Standards Documentation for states with regards to changes.

Suggested Fix
Seems it needs to be clear more. Provide sample output for new, existing and removed
State if the recommendation is to always to perform a diff rather than something different, using the standard salt diff for a hash.
Provide an example of using the salt diff for a hash.

Type of documentation
Writing States

Location or format of documentation
https://docs.saltproject.io/en/latest/ref/states/writing.html

Additional context

          ID: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\RemoteAccess\Parameters\AccountLockout
    Function: reg.present
      Result: True
     Comment: Added ABC to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\RemoteAccess\Parameters\Something
     Started: 15:50:09.107961
    Duration: 8.831 ms
     Changes:
              ----------
              reg:
                  ----------
                  Added:
                      ----------
                      Entry:
                          ABC
                      Inheritance:
                          True
                      Key:
                          HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\RemoteAccess\Parameters\Something
                      Owner:
                          None
                      Perms:
                          ----------
                          Deny:
                              None
                          Grant:
                              None
                      Value:
                          99
 salt minion reg.read_value HKEY_LOCAL_MACHINE 'SYSTEM\CurrentControlSet\Services\RemoteAccess\Parameters\Something' 'ABC'
minion:
    ----------
    hive:
        HKEY_LOCAL_MACHINE
    key:
        SYSTEM\CurrentControlSet\Services\RemoteAccess\Parameters\Something
    success:
        True
    vdata:
        99
    vname:
        ABC
    vtype:
        REG_DWORD

e.g. Persuado code

   before =  __salt__['module.read_something'] # if it does not exist should be set to empty hash/dict
   make changes
   after = __salt__['module.read_something'] # if it does not exist should be set to empty hash/dict
   changes = dict_diff(before, after)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the Salt states writing documentation at the linked writing.html location and review how changes are currently described. Use the provided reg.present output and read_value example to identify what is missing for new, existing, and removed states, including the proposed hash diff example. Done means the recommendation and expected change output are clear for each case.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.