Development Guide

Prerequisites

• Git
• Bash 4.0+
• Python 3.8+
• WP-CLI (for testing against WordPress)
• Bats (for running Bash tests)

Setup

git clone git@github.com:donnyaw/wp-seo-ops.git
cd wp-seo-ops
python3 -m venv .venv
source .venv/bin/activate
pip install -r python/requirements.txt

Development Workflow

Running Tests

# Full test suite
make test

# Just lint
make lint

# Just smoke tests
make smoke

# Just bats tests
make bats-test

Adding a New Command

1. Create the command file in src/commands/<name>/<name>.sh
2. Add subcommand functions following the existing patterns
3. Wire it up in src/wp-seo-ops (add to show_help() and main() case)
4. If it needs Python analysis, create a module in python/wp_seo_ops/
5. Write bats tests in tests/bash/test_<name>.bats
6. Update development-plan.csv status
7. Run make test

Code Style

• Bash: Use set -euo pipefail, prefer functions over scripts, use local variables
• Python: Use type hints, follow PEP 8, handle errors gracefully
• Command groups and complex subcommands: Provide --help; commands that emit diagnostic output should support --debug and --no-color where applicable
• Write/delete commands: Must support --dry-run; delete commands must require confirmation or an explicit force flag

Adding SEO Plugin Support

1. Add detection in seo-adapter.sh (_detect_plugin_by_slug())
2. Add meta key mappings in seo-adapter.sh (_yoast_meta_key(), _seopress_meta_key(), etc.)
3. Add tests in test_libraries.bats
4. Test with a real WordPress installation

Project Management

The source of truth is development-plan.csv:

Column	Description
id	Task ID
phase	Development phase
status	plan, done, pending, canceled
priority	critical, high, medium, low
category	Feature category
command	Command name
description	Task description
dependencies	Comma-separated task IDs
detail_path	Path to detailed spec
tier	Priority tier
mvp	MVP scope (yes/no)
risk	low, medium, high