# Contributing

## Code standards

The following apply across the whole module suite:

- PHP 8.3+ with `declare(strict_types=1)` on every file.
- [Drupal coding standards](https://www.drupal.org/docs/develop/standards) (Drupal + DrupalPractice rulesets).
- US English spelling in code, comments, and commit messages.
- Entity types declared via PHP 8 `#[ContentEntityType]` attributes, not `@ContentEntityType` annotations.
- Test metadata via PHPUnit attributes (`#[Group]`, `#[CoversClass]`, etc.), not docblock annotations.

### What CI enforces today

The DrupalCI-backed GitLab pipeline runs these jobs on every push and blocks merges on failure unless noted:

- **phpcs** — Drupal + DrupalPractice rulesets
- **phpstan** — configured in `phpstan.neon`
- **cspell** — spell checking (project words in `.cspell-project-words.txt`)
- **eslint** — JavaScript under `modules/` and `css/`
- **stylelint** — CSS under `modules/` and `css/`
- **phpunit** — full test suite with code-coverage (coverage is published, not gated)
- **upgrade status** — advisory only (`allow_failure: true`); flags `new static()` in plugin `create()` methods which is the standard Drupal pattern.

### Conventions (not CI-enforced)

These are project standards — reviewers will flag them, but the pipeline doesn't fail a branch for violating them:

- `declare(strict_types=1)` on every PHP file.
- US English spelling (cspell catches the big cases, but reviewers still look).
- PHP 8 attributes over annotations (phpstan catches obvious annotation-only definitions; relying on the lint is not complete).
- Kernel tests using `#[RunTestsInSeparateProcesses]` — required to run green under PHPUnit 11, but not independently verified.

## Testing

Every new feature needs tests:

- **Unit tests** for API classes and sync mapping logic (mock all Drupal services).
- **Kernel tests** for entities, plugins, forms, and integration behavior.

For test fixture data with WoW proper nouns, use `// cspell:disable-next-line` inline. Production vocabulary (drush aliases, Drupal terms, domain jargon) goes in `.cspell-project-words.txt`.

Run locally:

```
ddev exec 'cd /var/www/html/web/core && SIMPLETEST_DB=sqlite://localhost/:memory: ../../vendor/bin/phpunit /path/to/tests'
```

## Issue tracker

Report bugs and feature requests on the [drupal.org issue queue](https://www.drupal.org/project/issues/wow).
