(MODULES-11816) Add CLAUDE.md for Claude Code guidance#1676
Conversation
Document the module's three-layer architecture (globals → params → server), custom types/providers, Hiera data layout, validate/spec/Litmus commands, spec conventions, lint customizations, and how the CI matrix is built.
Branch names now follow <module-id>-<short-change-related-name> (e.g. MODULES-11816-add-claude-md) instead of just the bare ticket id. Test-PR runs of community PRs still use the <module-id>-pr<upstream-pr-number> pattern.
|
|
||
| ## Module overview | ||
|
|
||
| `puppetlabs-postgresql` manages PostgreSQL packages, services, databases, roles, grants, and `pg_hba.conf` / `pg_ident.conf` rules across RHEL-family, Debian-family, SLES, Arch, Gentoo, FreeBSD, and OpenBSD. The Puppet Forge entry point is `class { 'postgresql::server': }`, but every consumer is expected to declare `postgresql::globals` first (see Architecture). |
There was a problem hiding this comment.
a bunch of information in this document is duplicated from other places. For the past decade, we tried to avoid this. For example you list various operating systems here. How do you ensure that the list is correct? How do you update it? How do people know which list is the authoritative source?
There was a problem hiding this comment.
The intent of CLAUDE.md is to give Claude Code enough context in one read that it doesn't have to grep the repo for basics. PR #1650 just changed the OS list, so this is a real risk.
Let me refactor the file so it only contains things that aren't discoverable elsewhere — primarily the architecture write-up (globals → params → server, the default-vs-versioned package-name branch, why globals must be included first, how the CI matrix is actually generated). For everything else I'll just point at the authoritative file (metadata.json for supported OSes/dependencies, .puppet-lint.rc for lint config, REFERENCE.md for class docs, lib/puppet/ for custom resources). Will push that.
… sources Address review feedback from @bastelfreak: drop content that duplicates existing single-sources-of-truth (OS list, dependency versions, lint disabled-checks, custom type/provider enumeration, spec subdirectory listing). Replace with an explicit "Authoritative sources" table that points readers at the real file for each piece of information. Keeps the non-discoverable content: three-layer architecture, the default-vs-versioned package-name branch in params.pp, the include_examples convention, and how the CI matrix is actually built.
| Assume `bundle install --path=vendor` has been run. | ||
|
|
||
| ```sh | ||
| bundle exec rake validate # puppet syntax + lint + metadata-json-lint (run before pushing) | ||
| bundle exec rake parallel_spec # full unit suite, parallelized — preferred over `rake spec` for full runs | ||
| bundle exec rspec spec/classes/globals_spec.rb # one file | ||
| bundle exec rspec spec/classes/globals_spec.rb -e "RedHat 8" # one example | ||
|
|
||
| bundle exec rake 'litmus:provision[docker,litmusimage/almalinux:9]' | ||
| bundle exec rake 'litmus:install_agent' | ||
| bundle exec rake 'litmus:install_module' | ||
| bundle exec rake 'litmus:acceptance:parallel' | ||
| bundle exec rake 'litmus:tear_down' | ||
|
|
||
| bundle exec rake strings:generate:reference # regenerate REFERENCE.md after editing puppet-strings annotations | ||
| ``` |
There was a problem hiding this comment.
That's all generic information, not module specific. This really doesn't belong in every module. Can't you put it into the pdk docs or your website or a CONTRIBUTING.md at the org level? For the community, we have https://voxpupuli.org/docs/how_to_run_tests/ . I know I'm repeating myself, but: I highly recommend to discuss big changes, like introduction of claude code, with the community and your partners.
Address review feedback from @bastelfreak: drop generic Puppet-module content (commands, lint config, CI mechanics, spec helpers, branch conventions) that belongs in PDK docs or org-level documentation, not duplicated into every module. Keeps only what is specific to puppetlabs-postgresql and not derivable from reading individual files: the three-layer architecture (globals -> params -> server), the default-vs-versioned package-name branch in params.pp, the multi-instance RHEL-8-only caveat, and the Hiera data/os layout.
2 participants
Summary
Adds a
CLAUDE.mdat the module root to give Claude Code (claude.ai/code) the context it needs to work productively in this repository.The file covers:
postgresql::globals→params.pp→postgresql::serverand whyglobalsmust be included first.params.ppdefault-vs-versioned package-name branch that's easy to break when adding OS support.lib/puppet/(postgresql_psql,postgresql_conf,postgresql_conn_validator,postgresql_replication_slot) and how theserver/*defined types funnel throughpostgresql_psql.data/os/...) and thehiera.yamlhierarchy.rake validate,rake parallel_spec, single-file/example rspec, full Litmus provision/install/run/teardown cycle, andpuppet-stringsreference regeneration.classes/,defines/,functions/,type_aliases/,unit/,acceptance/) and theshared_contextpattern inspec/spec_helper_local.rb..puppet-lint.rcand theRakefile.matrix_from_metadata_v3×puppet_litmus/exe/matrix.json).<module-id>-<short-change-related-name>prefix,Co-authored-by:trailer for community-PR cherry-picks).Supersedes #1675 (auto-closed during branch rename).
Test plan