saltstack / saltstack/salt

Docs for `deb_postgres` should state the module only complements `modules/postgres.py`

Open
#64,022 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

debian documentation help-wanted module doc standards severity-medium time-estimate-quick-fix
Dominant language
Python
Stars
15.7k
Forks
5.6k
Avg merge
2d 44m
Merged PRs (30d)
80

Description

Description of Issue

In short: Looking a both the docs and the code of modules/deb_postgres.py and modules/postgres.py I didn't realize they complement each other.

Working on the (pretty outdated) postgresql-formula I got rather confused about which modules were available on which platform at which point in the deployment.
Looking at the code to figure out when the postgres exec module got loaded I first suspected the deb_postgres module would prevent the postgres one being loaded as at one point my Debian and Ubuntu minions were lacking a some postgres* state functions. The docs on the __virtual__ function also have a note stating "Modules which return a string from __virtual__ that is already used by a module that ships with Salt will override the stock module." which didn't help either.

Setup

A set of KVM guests with a Debian 11 master and minions running Debian 11 & 12, Ubuntu 22.04, CentOS 7, Alpine 317, FreeBSD 13 to make sure at least critical things work with and without platform specific quirks.

Steps to Reproduce Issue

(Sorry, hard to tell when I stumbled over this first)

Versions Report

All the Debian-based VMs run v3005.1 onedir/singlebin from repo.saltproject.io:

kvm-master:~# salt-call --versions-report
Salt Version:
          Salt: 3005.1
 
Dependency Versions:
          cffi: 1.14.6
      cherrypy: 18.6.1
      dateutil: 2.8.1
     docker-py: Not Installed
         gitdb: Not Installed
     gitpython: Not Installed
        Jinja2: 3.1.0
       libgit2: 1.5.0
      M2Crypto: Not Installed
          Mako: Not Installed
       msgpack: 1.0.2
  msgpack-pure: Not Installed
  mysql-python: Not Installed
     pycparser: 2.21
      pycrypto: Not Installed
  pycryptodome: 3.9.8
        pygit2: 1.11.1
        Python: 3.9.16 (main, Jan  6 2023, 22:49:58)
  python-gnupg: 0.4.8
        PyYAML: 5.4.1
         PyZMQ: 23.2.0
         smmap: Not Installed
       timelib: 0.2.4
       Tornado: 4.5.3
           ZMQ: 4.3.4
 
System Versions:
          dist: debian 11 bullseye
        locale: utf-8
       machine: x86_64
       release: 5.10.0-21-amd64
        system: Linux
       version: Debian GNU/Linux 11 bullseye

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 by comparing the documentation and code in modules/deb_postgres.py and modules/postgres.py, focusing on how platform-specific module availability is described. Update the relevant module documentation so it clearly states that deb_postgres complements modules/postgres.py and explains their relationship; done means a reader can understand which module is available on Debian-based platforms without inferring it from the code.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.