# Contributing Guide

## Prerequisites

- PHP 7.4+ (for local development; plugin supports 5.3+ at runtime)
- Node.js + npm
- Composer
- WordPress local environment (e.g. LocalWP, DDEV, or Docker)
- Git

## Setup

```bash
# Clone the repository
git clone https://github.com/brainstormforce/convertplug.git
cd convertplug

# Install PHP dev dependencies (WPCS, PHPStan, stubs)
composer install

# Install Node dependencies (Grunt, linting)
npm install
```

## Branching

| Branch | Purpose |
|--------|---------|
| `master` | Stable release branch |
| `dev` | Active development branch |
| Feature branches | Branch from `dev`, named descriptively |

**Always branch from `dev` for new features and bug fixes.** Target PRs at `dev`, not `master`.

## Coding Standards

### PHP

- Follow **WordPress Coding Standards (WPCS)**
- Use PHPCS to validate before committing: `composer run lint`
- Auto-fix what you can: `composer run format`
- All user-facing strings must use `esc_html__()`, `esc_attr__()`, or `esc_html_e()` with text domain `smile`
- All output must be escaped: `esc_html()`, `esc_attr()`, `esc_url()`, `wp_kses()`
- All database interactions must use `$wpdb->prepare()` for parameterised queries
- Always verify nonces before processing form data
- Always check `current_user_can( 'access_cp' )` or appropriate capability on admin actions
- Never use `extract()`; reference array keys explicitly
- Early returns over deeply nested conditionals

### JavaScript

- Follow `@wordpress/scripts` ESLint rules
- Run: `npm run lint:js`
- No `console.log` in committed code
- Use `wp.i18n.__()` or `wp.i18n.sprintf()` for translatable JS strings

### CSS

- Follow `@wordpress/stylelint-config`
- Run: `npm run lint:css`
- Use RTL-compatible CSS; Grunt generates `.rtl.css` variants

## Commit Messages

Write commits focused on **why**, not what:

```
# Good
Fix subscriber count not updating after import
Improve performance of analytics day-range queries

# Avoid
Fixed bug
Updated file
```

Use conventional prefixes where meaningful: `fix:`, `feat:`, `improvement:`, `security:`.

## Pull Request Checklist

Before submitting a PR:

- [ ] `composer run lint` passes with no new violations
- [ ] `composer run phpstan` passes (no new errors outside baseline)
- [ ] `npm run lint:js` passes
- [ ] `npm run lint:css` passes
- [ ] Manual testing performed (see [Testing Guide](Testing-Guide))
- [ ] No hardcoded credentials, secrets, or API keys
- [ ] All new strings use text domain `smile`
- [ ] All admin AJAX handlers verify nonces
- [ ] No debug code (`var_dump`, `print_r`, `console.log`) left in
- [ ] `changelog.txt` entry added

## Security Requirements

All code must adhere to WordPress security best practices:

| Rule | Implementation |
|------|---------------|
| Nonce verification | `wp_verify_nonce()` on all form/AJAX handlers |
| Capability checks | `current_user_can( 'access_cp' )` for all admin actions |
| Input sanitisation | `sanitize_text_field()`, `sanitize_email()`, `intval()`, etc. |
| Output escaping | `esc_html()`, `esc_attr()`, `esc_url()`, `wp_kses_post()` |
| SQL safety | `$wpdb->prepare()` — never interpolate user input into SQL |
| Direct access prevention | `defined( 'ABSPATH' ) || die()` at top of every PHP file |

## Adding a New Feature

1. Create a branch from `dev`
2. Add the feature with full WPCS-compliant code
3. Add/update any translatable strings (run `npm run i18n` to rebuild `.pot`)
4. If adding new AJAX actions: register them in `admin/ajax-actions.php`, add nonce, add capability check
5. Update `changelog.txt`
6. Submit a PR against `dev`

## Releasing

Releases are managed by the Brainstorm Force team:

1. Version bump via `grunt bumpup` (updates `package.json`, `convertplug.php`, `changelog.txt`)
2. Assets compiled and minified
3. ZIP artifact created via `grunt compress`
4. Release published to CodeCanyon / auto-update server

## Related Pages

- [Testing Guide](Testing-Guide)
- [Build Tooling](Build-Tooling)
- [Architecture Overview](Architecture-Overview)