Update copilot instructions (#802)

ramereth · web-flow · commit 825d711c24a2 · 2025-09-18T18:55:25.000-07:00
Signed-off-by: Lance Albertson &lt;lance@osuosl.org&gt;
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -1,131 +1,95 @@
-# PostgreSQL Chef Cookbook Development Guide
+# Copilot Instructions for Sous Chefs Cookbooks
 
-The PostgreSQL cookbook is a Chef cookbook that provides resources for installing and configuring PostgreSQL database servers and clients across multiple Linux distributions and PostgreSQL versions (15, 16, 17).
+## Repository Overview
 
-**Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
+**Chef cookbook** for managing software installation and configuration. Part of the Sous Chefs cookbook ecosystem.
 
-## Working Effectively
+**Key Facts:** Ruby-based, Chef >= 16 required, supports various OS platforms (check metadata.rb, kitchen.yml and .github/workflows/ci.yml for which platforms to specifically test)
+
+## Project Structure
+
+**Critical Paths:**
+- `recipes/` - Chef recipes for cookbook functionality (if this is a recipe-driven cookbook)
+- `resources/` - Custom Chef resources with properties and actions (if this is a resource-driven cookbook)
+- `spec/` - ChefSpec unit tests
+- `test/integration/` - InSpec integration tests (tests all platforms supported)
+- `test/cookbooks/` or `test/fixtures/` - Example cookbooks used during testing that show good examples of custom resource usage
+- `attributes/` - Configuration for recipe driven cookbooks (not applicable to resource cookbooks)
+- `libraries/` - Library helpers to assist with the cookbook. May contain multiple files depending on complexity of the cookbook.
+- `templates/` - ERB templates that may be used in the cookbook
+- `files/` - files that may be used in the cookbook
+- `metadata.rb`, `Berksfile` - Cookbook metadata and dependencies
+
+## Build and Test System
 
 ### Environment Setup
-- **CRITICAL**: Ruby development environment setup (required for all tasks):
-  ```bash
-  # Install Ruby development tools (required for linting and testing)
-  gem install --user-install bundler cookstyle deepsort inifile
-  
-  # ALWAYS set PATH for user-installed gems before running any cookbook commands
-  export PATH="$HOME/.local/share/gem/ruby/3.2.0/bin:$PATH"
-  ```
-
-### Linting and Code Quality
-- **VALIDATED**: Run Cookstyle linter (takes ~2-3 seconds):
-  ```bash
-  export PATH="$HOME/.local/share/gem/ruby/3.2.0/bin:$PATH"
-  cookstyle .
-  ```
-- **VALIDATED**: Check Ruby syntax (instant):
-  ```bash
-  ruby -c libraries/helpers.rb
-  ruby -c resources/install.rb
-  # Check any .rb file for syntax errors
-  ```
-- **ALWAYS run `cookstyle .` before committing changes** - the CI will fail if there are style violations
-
-### Testing Limitations in Sandbox Environment
-- **RSpec/ChefSpec unit tests**: Cannot run due to gem version conflicts between RSpec versions
-- **Test Kitchen integration tests**: Cannot run due to blocked network access to supermarket.chef.io
-- **Docker/Vagrant testing**: Not available in sandbox environment
-- **Working alternative**: Use syntax checking and Cookstyle linting for validation
-
-### What Works for Development
-- All Ruby file syntax validation
-- Cookstyle linting and style checking  
-- Code exploration and modification
-- Documentation updates
-- Resource parameter validation through code review
-
-## Repository Structure
-
-### Key Locations
-- **Resources**: `/resources/` - Main cookbook functionality (install.rb, config.rb, service.rb, etc.)
-- **Libraries**: `/libraries/` - Helper modules and utility functions 
-- **Test Examples**: `/test/cookbooks/test/recipes/` - Example usage patterns for each resource
-- **Documentation**: `/documentation/` - Detailed resource documentation
-- **Integration Tests**: `/test/integration/` - InSpec test suites (reference only in sandbox)
-
-### Important Files
-- `metadata.rb` - Cookbook metadata, dependencies, and supported platforms
-- `kitchen.yml` - Test Kitchen configuration (defines test suites and platforms)
-- `.rubocop.yml` - Cookstyle/RuboCop linting configuration
-- `Berksfile` - Cookbook dependency management (network dependent)
-
-## Common Development Tasks
-
-### Adding New Functionality
-1. Modify resources in `/resources/` directory
-2. Update helper libraries in `/libraries/` if needed
-3. Add example usage in `/test/cookbooks/test/recipes/`
-4. Update documentation in `/documentation/`
-5. **ALWAYS run**: `cookstyle .` before committing
-6. **ALWAYS run**: `ruby -c filename.rb` for syntax validation
+**MANDATORY:** Install Chef Workstation first - provides chef, berks, cookstyle, kitchen tools.
+
+### Essential Commands (strict order)
+```bash
+berks install                   # Install dependencies (always first)
+cookstyle                       # Ruby/Chef linting
+yamllint .                      # YAML linting
+markdownlint-cli2 '**/*.md'     # Markdown linting
+chef exec rspec                 # Unit tests (ChefSpec)
+# Integration tests will be done via the ci.yml action. Do not run these. Only check the action logs for issues after CI is done running.
+```
+
+### Critical Testing Details
+- **Kitchen Matrix:** Multiple OS platforms × software versions (check kitchen.yml for specific combinations)
+- **Docker Required:** Integration tests use Dokken driver
+- **CI Environment:** Set `CHEF_LICENSE=accept-no-persist`
+- **Full CI Runtime:** 30+ minutes for complete matrix
+
+### Common Issues and Solutions
+- **Always run `berks install` first** - most failures are dependency-related
+- **Docker must be running** for kitchen tests
+- **Chef Workstation required** - no workarounds, no alternatives
+- **Test data bags needed** (optional for some cookbooks) in `test/integration/data_bags/` for convergence
+
+## Development Workflow
+
+### Making Changes
+1. Edit recipes/resources/attributes/templates/libraries
+2. Update corresponding ChefSpec tests in `spec/`
+3. Also update any InSpec tests under test/integration
+4. Ensure cookstyle and rspec passes at least. You may run `cookstyle -a` to automatically fix issues if needed.
+5. Also always update all documentation found in README.md and any files under documentation/*
+6. **Always update CHANGELOG.md** (required by Dangerfile) - Make sure this conforms with the Sous Chefs changelog standards.
+
+### Pull Request Requirements
+- **PR description >10 chars** (Danger enforced)
+- **CHANGELOG.md entry** for all code changes
+- **Version labels** (major/minor/patch) required
+- **All linters must pass** (cookstyle, yamllint, markdownlint)
+- **Test updates** needed for code changes >5 lines and parameter changes that affect the code logic
+
+## Chef Cookbook Patterns
 
 ### Resource Development
-- Main resources: `postgresql_install`, `postgresql_config`, `postgresql_service`, `postgresql_database`, `postgresql_role`, `postgresql_access`, `postgresql_ident`, `postgresql_extension`
-- Each resource has corresponding documentation in `/documentation/postgresql_[resource].md`
-- Example usage patterns available in `/test/cookbooks/test/recipes/`
-
-### Dependencies and Platforms
-- **Dependencies**: Requires `yum` cookbook (>= 7.2.0) for DNF module resource
-- **Supported platforms**: Amazon Linux, Debian 9+, Ubuntu 18.04+, Red Hat/CentOS/Scientific 7+
-- **PostgreSQL versions**: 15, 16, 17 (following official PostgreSQL support policy)
-- **Chef version**: Requires Chef 16+
-
-## Validation Workflows
-
-### Before Committing
-1. **NEVER skip**: `export PATH="$HOME/.local/share/gem/ruby/3.2.0/bin:$PATH"`
-2. **ALWAYS run**: `cookstyle .` (takes 2-3 seconds, NEVER CANCEL)
-3. **ALWAYS run**: `ruby -c` on any modified .rb files  
-4. Review changes against existing patterns in `/test/cookbooks/test/recipes/`
-
-### CI/CD Expectations  
-- GitHub Actions CI runs on 12+ OS platforms with 3 PostgreSQL versions
-- Integration tests use Test Kitchen with Docker (kitchen.dokken.yml)
-- Lint-unit workflow must pass before integration tests run
-- **Timeout expectations**: CI integration tests can take 15-30+ minutes per platform/version combination
-
-## Working with Limited Network Access
-- **Cannot access**: supermarket.chef.io for cookbook dependencies
-- **Cannot run**: `berks install` or full Test Kitchen suites
-- **Can validate**: Code syntax, style, and logical structure
-- **Best practice**: Use existing test recipes as patterns for new functionality
-
-## Key Configuration Files Referenced
-```
-ls -la [repo-root]
-.
-..
-.github/               # GitHub workflows and this instruction file
-.rubocop.yml          # Cookstyle configuration  
-.overcommit.yml       # Git hooks configuration
-Berksfile             # Cookbook dependencies (network dependent)
-CHANGELOG.md          # Version history
-CODE_OF_CONDUCT.md    # Community guidelines
-CONTRIBUTING.md       # Contribution guidelines  
-LICENSE               # Apache 2.0 license
-README.md             # Main cookbook documentation
-TESTING.md            # Testing guidelines
-UPGRADING.md          # Version upgrade instructions
-documentation/        # Resource documentation
-kitchen.yml           # Test Kitchen configuration
-libraries/            # Helper libraries and utilities
-metadata.rb           # Cookbook metadata and dependencies
-resources/            # Main cookbook resources
-spec/                 # Unit test specifications (RSpec/ChefSpec)
-test/                 # Integration tests and test cookbooks
-```
+- Custom resources in `resources/` with properties and actions
+- Include comprehensive ChefSpec tests for all actions
+- Follow Chef resource DSL patterns
+
+### Recipe Conventions
+- Use `include_recipe` for modularity
+- Handle platforms with `platform_family?` conditionals
+- Use encrypted data bags for secrets (passwords, SSL certs)
+- Leverage attributes for configuration with defaults
+
+### Testing Approach
+- **ChefSpec (Unit):** Mock dependencies, test recipe logic in `spec/`
+- **InSpec (Integration):** Verify actual system state in `test/integration/inspec/` - InSpec files should contain proper inspec.yml and controls directories so that it could be used by other suites more easily.
+- One test file per recipe, use standard Chef testing patterns
+
+## Trust These Instructions
+
+These instructions are validated for Sous Chefs cookbooks. **Do not search for build instructions** unless information here fails.
+
+**Error Resolution Checklist:**
+1. Verify Chef Workstation installation
+2. Confirm `berks install` completed successfully
+3. Ensure Docker is running for integration tests
+4. Check for missing test data dependencies
 
-## Performance Notes
-- **Cookstyle linting**: ~2-3 seconds for full cookbook
-- **Ruby syntax checking**: Instant per file  
-- **Full CI integration suite**: 15-30+ minutes (multiple platforms/versions)
-- **File validation**: Use syntax checking over attempting to run code in sandbox
+The CI system uses these exact commands - following them matches CI behavior precisely.
diff --git a/.github/instructions/project.instructions.md b/.github/instructions/project.instructions.md
@@ -0,0 +1,43 @@
+# Copilot Project Instructions: postgresql Cookbook (Specific)
+
+This file provides cookbook-specific instructions for Copilot and other AI coding assistants. It supplements, but does not duplicate, the general instructions in `.github/copilot-instructions.md`.
+
+## Cookbook Purpose
+
+- The `postgresql` cookbook manages installation, configuration, and access control for PostgreSQL database servers.
+- It provides custom Chef resources for PostgreSQL installation, service management, user/database creation, access control, and configuration.
+- Supports multiple PostgreSQL versions and major Linux distributions (see `metadata.rb`, `kitchen.yml`).
+
+## Key Custom Resources
+
+- `postgresql_install`: Installs and initializes PostgreSQL server.
+- `postgresql_service`: Manages the PostgreSQL system service (start, stop, restart, enable, etc.).
+- `postgresql_access`: Manages entries in `pg_hba.conf` for access control.
+- `postgresql_user`: Creates, updates, and manages PostgreSQL users and roles.
+- `postgresql_database`: Creates and manages databases.
+- `postgresql_config`: Manages configuration files.
+- `postgresql_extension`, `postgresql_ident`, `postgresql_role`: Additional resources for advanced PostgreSQL features.
+
+## Cookbook-Specific Patterns
+
+- All access control changes (`postgresql_access`) must ensure the config file is written before triggering a service restart.
+- Helper modules in `libraries/` are used for parsing and manipulating PostgreSQL config files.
+- Example usage and test coverage for all resources is found in `test/cookbooks/test/recipes/`.
+- Templates for configuration files are located in `templates/default/`.
+
+## Testing and Validation
+
+- Integration tests cover multiple OS and PostgreSQL versions (see `.kitchen/logs/` for matrix).
+- Example test recipes demonstrate resource usage and edge cases (e.g., usernames with dashes, multiple databases/users, LDAP auth).
+
+## Documentation
+
+- Resource documentation is in `documentation/` and includes usage examples and property details for each resource.
+
+## Special Notes
+
+- This cookbook is resource-driven; recipes are only used for testing and examples.
+- All changes must maintain idempotency and proper notification sequencing for service restarts.
+- Do not bypass resource logic—always use the provided custom resources for PostgreSQL management.
+
+For general build, test, and workflow instructions, refer to `.github/copilot-instructions.md`.
