Skip to content

Update copilot instructions #802

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 19, 2025
Merged

Update copilot instructions #802

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
210 changes: 87 additions & 123 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
43 changes: 43 additions & 0 deletions .github/instructions/project.instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.
Loading