| 1 |
# Contributing Guide |
| 2 |
|
| 3 |
This guide covers how to contribute to CartFlows — branch strategy, commit conventions, code review process, and the development workflow. |
| 4 |
|
| 5 |
## Prerequisites |
| 6 |
|
| 7 |
Before contributing, ensure you have: |
| 8 |
|
| 9 |
- **PHP** 7.2 or higher |
| 10 |
- **Node.js** and **npm** (check `package.json` engines field) |
| 11 |
- **Composer** |
| 12 |
- **Docker** (for wp-env E2E tests) |
| 13 |
- **Git** |
| 14 |
- **WordPress** local environment (wp-env or equivalent) |
| 15 |
|
| 16 |
## Development Setup |
| 17 |
|
| 18 |
```bash |
| 19 |
# 1. Clone the repository |
| 20 |
git clone <repo-url> |
| 21 |
cd cartflows |
| 22 |
|
| 23 |
# 2. Install PHP dependencies |
| 24 |
composer install |
| 25 |
|
| 26 |
# 3. Install JS dependencies (also installs pre-commit hook) |
| 27 |
npm install |
| 28 |
|
| 29 |
# 4. Start development watch mode |
| 30 |
npm run start |
| 31 |
|
| 32 |
# 5. (Optional) Start wp-env Docker environment for E2E tests |
| 33 |
npm run env:start |
| 34 |
``` |
| 35 |
|
| 36 |
## Branch Strategy |
| 37 |
|
| 38 |
| Branch | Purpose | |
| 39 |
|--------|---------| |
| 40 |
| `master` | Production-ready code. All releases are tagged here. | |
| 41 |
| `dev` | Main integration branch. PRs target this branch. | |
| 42 |
| `feature/<name>` | Feature branches | |
| 43 |
| `fix/<name>` | Bug fix branches | |
| 44 |
| `chore/<name>` | Build, tooling, dependency updates | |
| 45 |
| `docs/<name>` | Documentation-only changes | |
| 46 |
|
| 47 |
### Workflow |
| 48 |
|
| 49 |
1. Branch from `dev` |
| 50 |
2. Implement your change |
| 51 |
3. Run all linters and tests |
| 52 |
4. Build assets: `npm run build` |
| 53 |
5. Open PR targeting `dev` |
| 54 |
6. After review and approval, merge via squash or merge commit |
| 55 |
7. Periodically, `dev` is merged to `master` for releases |
| 56 |
|
| 57 |
## Commit Message Format |
| 58 |
|
| 59 |
CartFlows uses **Conventional Commits**: |
| 60 |
|
| 61 |
``` |
| 62 |
<type>: <short imperative description> |
| 63 |
|
| 64 |
[optional longer body] |
| 65 |
|
| 66 |
[optional footer, e.g. Closes #123] |
| 67 |
``` |
| 68 |
|
| 69 |
### Types |
| 70 |
|
| 71 |
| Type | When to use | |
| 72 |
|------|------------| |
| 73 |
| `feat:` | A new feature | |
| 74 |
| `fix:` | A bug fix | |
| 75 |
| `docs:` | Documentation only | |
| 76 |
| `chore:` | Build process, tooling, dependencies | |
| 77 |
| `refactor:` | Code refactoring (no behaviour change) | |
| 78 |
| `test:` | Adding or updating tests | |
| 79 |
| `style:` | Formatting, whitespace only | |
| 80 |
|
| 81 |
### Examples |
| 82 |
|
| 83 |
``` |
| 84 |
feat: add A/B testing support for checkout steps |
| 85 |
fix: fix order bump not appearing on mobile layouts |
| 86 |
docs: document REST API endpoints |
| 87 |
chore: update @wordpress/scripts to 19.2.2 |
| 88 |
refactor: move checkout field rendering to dedicated class |
| 89 |
``` |
| 90 |
|
| 91 |
## Pre-commit Hook |
| 92 |
|
| 93 |
`npm install` copies a pre-commit hook into `.git/hooks/`. This hook runs linting before every commit. |
| 94 |
|
| 95 |
If the hook blocks your commit, fix the violations it reports — do **not** bypass with `--no-verify` unless explicitly approved. |
| 96 |
|
| 97 |
## Before Opening a PR |
| 98 |
|
| 99 |
Run the complete quality check suite: |
| 100 |
|
| 101 |
```bash |
| 102 |
# PHP |
| 103 |
composer lint # PHPCS check |
| 104 |
composer phpstan # Static analysis |
| 105 |
composer test # Unit tests |
| 106 |
|
| 107 |
# JavaScript/CSS |
| 108 |
npm run lint-js # ESLint |
| 109 |
npm run lint-css # Stylelint |
| 110 |
npm run pretty # Prettier |
| 111 |
|
| 112 |
# Build |
| 113 |
npm run build # Rebuild compiled assets |
| 114 |
``` |
| 115 |
|
| 116 |
**Ensure build artifacts are committed.** If you changed any JS or SCSS files, run `npm run build` and include the updated files in `admin-core/assets/build/` in your PR. |
| 117 |
|
| 118 |
## PR Description |
| 119 |
|
| 120 |
Include in your PR description: |
| 121 |
1. **What** — What was changed and why |
| 122 |
2. **How to test** — Steps to verify the change manually |
| 123 |
3. **Screenshots** — For UI changes, include before/after screenshots |
| 124 |
4. **Related issues** — Link to any GitHub issues addressed |
| 125 |
|
| 126 |
## Code Review Standards |
| 127 |
|
| 128 |
Reviewers check for: |
| 129 |
|
| 130 |
- [ ] WordPress coding standards compliance (PHPCS passes) |
| 131 |
- [ ] PHPStan static analysis passes |
| 132 |
- [ ] All tests pass |
| 133 |
- [ ] Build artifacts updated (if JS/CSS changed) |
| 134 |
- [ ] Security: nonces verified, inputs sanitized, outputs escaped |
| 135 |
- [ ] No debug code (`console.log`, `var_dump`, `error_log`) |
| 136 |
- [ ] No hardcoded strings (use `__()` / `_e()` for translatable text) |
| 137 |
- [ ] Appropriate PHPDoc comments for new public methods |
| 138 |
|
| 139 |
## Adding New Features |
| 140 |
|
| 141 |
### Adding a PHP Module |
| 142 |
|
| 143 |
1. Create directory: `modules/{feature-name}/` |
| 144 |
2. Create main class: `modules/{feature-name}/class-cartflows-{feature}.php` |
| 145 |
3. Follow the singleton or loader pattern used by existing modules |
| 146 |
4. Register hooks in the constructor |
| 147 |
5. Load from `Cartflows_Loader` (or a parent module loader) |
| 148 |
|
| 149 |
### Adding a REST Endpoint |
| 150 |
|
| 151 |
1. Create class in `admin-core/api/` extending `ApiBase` |
| 152 |
2. Implement `register_routes()` method |
| 153 |
3. Register in `admin-core/api/api-init.php` |
| 154 |
4. Add nonce verification and capability checks |
| 155 |
|
| 156 |
### Adding an AJAX Handler |
| 157 |
|
| 158 |
1. Create class in `admin-core/ajax/` extending `AjaxBase` |
| 159 |
2. Call `$this->init_ajax_events( ['action_name'] )` in constructor |
| 160 |
3. Implement the `action_name()` method |
| 161 |
4. Register in `admin-core/ajax/ajax-init.php` |
| 162 |
|
| 163 |
### Adding a React Component |
| 164 |
|
| 165 |
1. Create component file in the appropriate `admin-core/assets/src/` subdirectory |
| 166 |
2. Follow existing component patterns (functional components + hooks) |
| 167 |
3. Use Tailwind CSS for styling |
| 168 |
4. Add to the appropriate app's component tree |
| 169 |
5. Run `npm run build` before committing |
| 170 |
|
| 171 |
## Internationalisation |
| 172 |
|
| 173 |
All user-facing strings must be internationalised: |
| 174 |
|
| 175 |
```php |
| 176 |
// PHP |
| 177 |
__( 'String to translate', 'cartflows' ) |
| 178 |
_e( 'String to echo', 'cartflows' ) |
| 179 |
``` |
| 180 |
|
| 181 |
```js |
| 182 |
// JavaScript |
| 183 |
import { __ } from '@wordpress/i18n'; |
| 184 |
__( 'String to translate', 'cartflows' ) |
| 185 |
``` |
| 186 |
|
| 187 |
Run `npm run i18n` to extract new strings. |
| 188 |
|
| 189 |
## Libraries Directory |
| 190 |
|
| 191 |
`libraries/` contains Composer-installed BSF packages (analytics, notices, nps-survey). These files are **committed** to the repo. Do not delete them. |
| 192 |
|
| 193 |
## Related Pages |
| 194 |
|
| 195 |
- [](WordPress-Coding-StandardsWordPress-Coding-Standards](WordPress-Coding-Standards](WordPress-Coding-Standards) |
| 196 |
- [](Testing-GuideTesting-Guide](Testing-Guide](Testing-Guide) |
| 197 |
- [](Build-SystemBuild-System](Build-System](Build-System) |
| 198 |
- [](Architecture-OverviewArchitecture-Overview](Architecture-Overview](Architecture-Overview) |
| 199 |
- [](Deployment-GuideDeployment-Guide](Deployment-Guide](Deployment-Guide) |
| 200 |
|
