Docs for `deb_postgres` should state the module only complements `modules/postgres.py`
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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