# Contributing

How to work on BW plugins in this repo.

## Getting set up

You should already have:

- Access to the server as a Linux user
- Membership in the `bw-plugins-dev` group (ask rian: `srv-gw grant-access --project bw-plugins --user <you>`)
- SSH / SFTP access to `mosiah.riverway.ca:2222`
- Claude Code installed if you want AI assistance

The dev site is at https://bw-plugins.demoing.info (behind demoing-auth; ask rian for the gate password).

## Workflow

1. **Understand the plugin.** Read `wp-content/plugins/bw-<slug>/CLAUDE.md`, `docs/SESSION-LOG.md`, `docs/SPEC.md`, `docs/ROADMAP.md`.
2. **Write code.** Follow [CLAUDE-STANDARDS.md](CLAUDE-STANDARDS.md).
3. **Test on the dev site.** Edit files directly; the bind mount means changes are immediate.
4. **Update docs as you go.** CHANGELOG.md and SESSION-LOG.md especially.
5. **Run scans.**
   ```bash
   tools/cleanup-scan.sh bw-<slug>
   tools/security-scan.sh bw-<slug>
   tools/test-plugin.sh bw-<slug>
   ```
6. **Release when ready** (rian only for now).

## Async communication

Use `docs/HANDOFF-NOTES.md` inside each plugin to pass context between sessions / collaborators. Format:

```markdown
### YYYY-MM-DD — from <name>

**Status:** Unread | Reviewed
**Context:** What you were doing
**Next step:** What should happen next
**Blockers:** Anything in the way
```

## Session log

`docs/SESSION-LOG.md` is an append-only history. Add an entry per substantive work session:

```markdown
## YYYY-MM-DD HH:MM — <dev name>

**Goal:** What we set out to do
**Done:** What got done
**Left off at:** Where we stopped
**Notes:** Anything worth remembering
```

Keep newest entries at the top.

## File permissions

WordPress (www-data) and developers (your user, via the `bw-plugins-dev` group) both need access to plugin files. The project directory is set up with group ownership `bw-plugins-dev` mode 2775 and default ACLs, so files you create should inherit the correct group.

If permissions get weird, run:

```bash
srv-gw fix-permissions --project bw-plugins
```

If you get "permission denied" editing files Claude or another collaborator created, you may need to refresh your Linux group membership: `newgrp bw-plugins-dev` or log out/in.

## What to avoid

- Don't edit `vendor/` — that's third-party code.
- Don't edit `/srv/apps/bw-plugins-dist/` directly — use `tools/release.sh`.
- Don't touch `/srv/apps/bwgeo/`, `/srv/apps/communityfinancials/`, or `bw-ai-schema-pro` anywhere. Those are the legacy setup, left alone until a planned future migration.
- Don't commit secrets to any file.
- Don't bypass the scan tools.

## Questions

- "How do I start a new plugin?" → [NEW-PLUGIN-GUIDE.md](NEW-PLUGIN-GUIDE.md)
- "How do I release?" → [RELEASE-PROCESS.md](RELEASE-PROCESS.md)
- "How do I do X securely?" → [SECURITY.md](SECURITY.md)
- "What are the code conventions?" → [CLAUDE-STANDARDS.md](CLAUDE-STANDARDS.md)
- Something else? → Ask rian, or check the per-plugin docs.