Contributing¶

We welcome contributions to the DDEV Kanopi Drupal Add-on! This guide will help you get started with contributing to the project.

Ways to Contribute¶

Report bugs - Found an issue? Let us know!
Request features - Have an idea for improvement?
Fix bugs - Submit pull requests for existing issues
Add features - Implement new functionality
Improve documentation - Help make our docs better
Write tests - Help improve test coverage

Getting Started¶

Prerequisites¶

Git
DDEV v1.22.0 or higher
Docker and Docker Compose
Bash (for testing scripts)
Bats (for running component tests)

Development Setup¶

Fork and clone the repository:

git clone https://github.com/yourusername/ddev-kanopi-drupal.git
cd ddev-kanopi-drupal

Create a test project:

mkdir test-project && cd test-project
ddev config --project-type=drupal --docroot=web --create-docroot

Install your local version:

ddev add-on get /path/to/your/ddev-kanopi-drupal

Test your changes:

# Run the full integration test
./tests/test-install.sh

# Or run component tests
bats tests/test.bats

Development Guidelines¶

Code Style¶

Shell Scripts¶

Use #!/usr/bin/env bash shebang
Use set -e for error handling
Include command descriptions and examples in comments
Follow existing patterns for variable naming and structure

Command Structure¶

All commands should follow this template:

#!/usr/bin/env bash

## Description: Brief description of what the command does
## Usage: command-name [arguments]
## Example: "ddev command-name arg1 arg2"

set -e

# Load configuration for web commands
if [[ "${BASH_SOURCE[0]}" == *"/commands/web/"* ]]; then
    source /var/www/html/.ddev/scripts/load-config.sh
    load_kanopi_config
fi

# Command logic here

Command Categories¶

Host Commands (`commands/host/`)¶

Execute on the host system outside DDEV containers
Can interact with local filesystem and external services
Examples: project-init, cypress-install, pantheon-terminus

Web Commands (`commands/web/`)¶

Execute inside the DDEV web container
Have access to Drupal environment and database
Can use environment variables from configuration
Examples: db-refresh, theme-build, recipe-apply

Configuration System¶

The add-on uses a three-tier configuration system:

Environment Variables: Stored in .ddev/config.yaml
Script Configuration: Shared via .ddev/scripts/load-config.sh
Interactive Configuration: Via ddev project-configure

When adding new configuration: - Update install.yaml for interactive prompts - Update load-config.sh for script access - Update documentation in docs/environment-variables.md

Testing¶

Required Tests¶

All contributions should include appropriate tests:

Command Tests: Add command checks to tests/test.bats
Integration Tests: Ensure tests/test-install.sh passes
Documentation Tests: Verify examples work as documented

Test Commands¶

# Run integration tests (comprehensive)
./tests/test-install.sh

# Run component tests (fast)
bats tests/test.bats

# Run specific test
bats tests/test.bats --filter "install from directory"

# Test in CI environment
DDEV_NONINTERACTIVE=true ./tests/test-install.sh

Test Environment¶

The test environment: - Creates temporary DDEV project with real Drupal - Tests interactive installation with automated responses - Validates all commands and configuration - Cleans up automatically on success - Preserves environment on failure for debugging

Contribution Workflow¶

1. Issue First¶

For significant changes, create an issue first to discuss: - Bug reports: Use the bug report template - Feature requests: Describe the use case and proposed solution - Questions: Ask for clarification on existing functionality

2. Development Process¶

Create a branch:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

Make your changes:
Follow the code style guidelines
Add appropriate tests
Update documentation

Test thoroughly:

# Test your specific changes
ddev add-on get .
ddev your-new-command

# Run full test suite
./tests/test-install.sh
bats tests/test.bats

Update documentation:
Update docs/commands.md for new commands
Update docs/configuration.md for new variables
Update README.md if needed
Add troubleshooting entries if applicable

3. Submission¶

Commit your changes:

git add .
git commit -m "feat: add new command for recipe management"
# or
git commit -m "fix: resolve database refresh timeout issue"

Push to your fork:

git push origin feature/your-feature-name

Create a Pull Request:
Use the PR template
Describe what your changes do
Include testing instructions
Reference any related issues

Pull Request Guidelines¶

PR Requirements¶

[ ] All tests pass (./tests/test-install.sh and bats tests/test.bats)
[ ] Documentation updated (commands, configuration, troubleshooting)
[ ] Follows existing code style and patterns
[ ] Includes appropriate tests for new functionality
[ ] Clear commit messages and PR description

PR Template¶

## Description
Brief description of changes and motivation

## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing
- [ ] Tests pass locally (`./tests/test-install.sh`)
- [ ] Added tests for new functionality
- [ ] Tested on multiple environments (Pantheon/Acquia)

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review of code completed
- [ ] Documentation updated
- [ ] No breaking changes to existing functionality

Cross-Repository Development¶

This add-on is part of a family that includes: - ddev-kanopi-wp - WordPress add-on - ddev-kanopi-drupal - This repository

Maintaining Consistency¶

When contributing to this repository, consider if changes should also be applied to the WordPress add-on:

Shared Components¶

Command patterns and naming conventions
Configuration system structure
Testing framework and patterns
Documentation organization
CI/CD workflows

Platform-Specific Components¶

Drupal-specific: Recipe commands, Drupal CLI integration
WordPress-specific: Block creation, WP-CLI integration
Hosting providers: Different platform support

Cross-Repository Workflow¶

Assess applicability: Determine if changes should be mirrored
Coordinate changes: Make equivalent changes in both repositories
Test both: Ensure functionality works in both contexts
Maintain compatibility: Keep command interfaces consistent

Command Development¶

Adding New Commands¶

Choose command type:
Host command: Runs on local machine
Web command: Runs inside DDEV container

Create command file:

# For host commands
touch commands/host/my-new-command
chmod +x commands/host/my-new-command

# For web commands
touch commands/web/my-new-command
chmod +x commands/web/my-new-command

Use command template:

#!/usr/bin/env bash

## Description: What this command does
## Usage: my-new-command [options]
## Example: "ddev my-new-command --flag value"

set -e

# Command logic here

Add to install.yaml:
Add removal line in removal_action section
Update command count in descriptions
Add tests:
Add command test to tests/test.bats
Test in integration test
Update documentation:
Add to docs/commands.md
Update README.md command overview
Add examples and usage instructions

Command Best Practices¶

Error handling: Use set -e and check return codes
User feedback: Provide clear output and progress indicators
Configuration: Use shared configuration system
Help text: Include usage examples and descriptions
Compatibility: Ensure commands work across platforms

Documentation¶

Documentation Structure¶

docs/ - MkDocs documentation source
mkdocs.yml - MkDocs configuration
README.md - Simplified overview with links to full docs

Writing Documentation¶

Use clear, concise language
Include code examples for all procedures
Use admonitions for warnings and tips
Test all code examples
Keep navigation intuitive

Building Documentation¶

# Install MkDocs
pip install mkdocs-material mkdocs-git-revision-date-localized-plugin

# Serve locally
mkdocs serve

# Build static site
mkdocs build

Release Process¶

Version Management¶

Releases are managed by maintainers using semantic versioning: - MAJOR.MINOR.PATCH (e.g., 1.2.3) - Breaking changes increment MAJOR - New features increment MINOR - Bug fixes increment PATCH

Release Checklist¶

Update version references in documentation
Run full test suite across environments
Update changelog
Create GitHub release with notes
Update documentation site

Community¶

Communication¶

GitHub Issues: Bug reports and feature requests
GitHub Discussions: General questions and ideas
Pull Requests: Code contributions and reviews

Code of Conduct¶

We follow the Contributor Covenant Code of Conduct. Please be respectful and inclusive in all interactions.

Getting Help¶

For Contributors¶

Review existing issues and pull requests
Check the troubleshooting guide
Ask questions in GitHub Discussions
Reach out to maintainers for major changes

For Users¶

Use GitHub Issues for bug reports
Check documentation first
Provide clear reproduction steps
Include debug information

Recognition¶

Contributors are recognized in: - GitHub Contributors page - Release notes for significant contributions - Documentation credits

Thank you for contributing to the DDEV Kanopi Drupal Add-on!