JezK

Edit File: Contributing-Guide.md

# Contributing Guide This guide covers the development workflow, build commands, coding standards, and commit conventions for the Modern Cart plugin. --- ## Prerequisites | Tool | Required Version | Notes | |------|-----------------|-------| | PHP | 7.4+ | Minimum runtime requirement | | Composer | 2.x | PHP dependency management | | Node.js | LTS | JS build tooling | | npm | 8+ | Package management | | WP-CLI | Any | For i18n and env commands | | WordPress | 5.4+ | Dev environment | | WooCommerce | 3.0+ | Required plugin | --- ## Initial Setup ```bash cd app/public/wp-content/plugins/modern-cart/ # PHP dependencies composer install # JS dependencies npm install ``` --- ## JavaScript / CSS Build Commands | Command | Description | |---------|-------------| | `npm run build` | Production build via `wp-scripts build` | | `npm run start` | Watch mode for development (live rebuilds) | | `npm run lint-js` | ESLint check (via `wp-scripts lint-js`) | | `npm run lint-js:fix` | Prettier + ESLint auto-fix | | `npm run lint-css` | Stylelint check (via `wp-scripts lint-style`) | | `npm run lint-css:fix` | Auto-fix CSS lint issues | | `npm run pretty` | Check Prettier formatting | | `npm run pretty:fix` | Auto-fix Prettier formatting | ### Build Entry Points `@wordpress/scripts` reads `webpack.config.js` which extends the default `wp-scripts` config. The main entry points are in `admin-core/` (for the React settings app). Built assets output to: - `admin-core/assets/build/` — Admin JS and CSS - `assets/` — Frontend JS and CSS (compiled separately) **Never edit files in `assets/` or `admin-core/assets/build/` directly.** These are build outputs. ### Tailwind CSS Tailwind CSS 3.x is configured in `tailwind.config.js`. PostCSS configuration is in `postcss.config.js`. The `@tailwindcss/forms` and `@tailwindcss/typography` plugins are included. --- ## PHP Build Commands | Command | Description | |---------|-------------| | `composer lint` | Run PHPCS (code standards check) | | `composer format` | Run PHPCBF (auto-fix PHPCS violations) | | `composer phpstan` | Run PHPStan static analysis (2GB memory limit) | | `composer test` | Run PHPUnit tests | | `composer insights` | Run PHPInsights code quality analysis | | `composer insights:fix` | Run PHPInsights with auto-fix | | `composer gen-stubs` | Generate PHPStan stubs from plugin artifacts | | `composer gen-baseline` | Regenerate PHPStan baseline | --- ## Grunt Commands Grunt handles minification, RTL CSS generation, text domain extraction, and ZIP packaging: ```bash # Run default grunt tasks (minify, RTL, etc.) grunt # Available grunt tasks (see Gruntfile.js for all): grunt cssmin # Minify CSS grunt uglify # Minify JS grunt rtlcss # Generate RTL CSS variants grunt clean # Clean build artifacts grunt compress # Create ZIP package grunt copy # Copy files to build directory ``` --- ## i18n Commands ```bash npm run i18n # Generate .pot file (with grunt textdomain extraction first) npm run i18n:po # Update .po files from .pot npm run i18n:mo # Compile .mo binaries npm run i18n:json # Generate JSON translation files for JavaScript # AI translation (requires gpt-po) npm run i18n:gptpo:nl # Dutch npm run i18n:gptpo:fr # French npm run i18n:gptpo:de # German npm run i18n:gptpo:es # Spanish npm run i18n:gptpo:it # Italian npm run i18n:gptpo:pt # Portuguese npm run i18n:gptpo:pl # Polish ``` --- ## Coding Standards ### PHP Standards Follow **WordPress Coding Standards (WPCS)**. Rulesets enforced in `phpcs.xml`: - `WordPress-Core` - `WordPress-Docs` - `WordPress-Extra` - `VIP-Go` - `PHPCompatibility` **Always run `composer format` before committing PHP changes.** #### Security Checklist - [ ] Sanitize all input: `sanitize_text_field()`, `absint()`, `sanitize_hex_color()`, `wp_unslash()` - [ ] Escape all output: `esc_html()`, `esc_attr()`, `esc_url()`, `wp_kses_post()` - [ ] Verify nonces before processing form/AJAX data: `wp_verify_nonce()` or `check_ajax_referer()` - [ ] Check capabilities before privileged actions: `current_user_can()` - [ ] Use `wp_safe_redirect()` not `wp_redirect()` - [ ] Prefix all global functions, hooks, option keys with `moderncart_` or `MODERNCART_` #### Namespace Convention All plugin classes must be in the `ModernCart\` namespace: - Feature classes: `ModernCart\Inc\ClassName` - Admin classes: `ModernCart\Admin_Core\ClassName` Files map to classes via the autoloader (camelCase → kebab-case): - `ModernCart\Inc\SlideOut` → `inc/slide-out.php` - `ModernCart\Admin_Core\AdminMenu` → `admin-core/admin-menu.php` #### Class Patterns - All feature classes use the `Get_Instance` trait (singleton) - All classes use `@since` tags in docblocks - Return types should be declared where possible (PHP 7.4+) - PHPStan must pass — do not add `@phpstan-ignore` for new code ### JavaScript Standards - React 18.x functional components with hooks - Redux for state management in the admin - ESLint rules from `@wordpress/eslint-plugin` - Prettier formatting from `@wordpress/prettier-config` - All translatable strings use `@wordpress/i18n` (`__()`, `_n()`, `_x()`) **Always run `npm run lint-js:fix` before committing JS changes.** ### CSS Standards - Tailwind CSS utility classes in JSX/TSX - Custom component CSS in PostCSS - RTL support via `grunt-rtlcss` - CSS class naming: `moderncart-` prefix for all plugin classes --- ## Text Domain All translatable strings must use the `modern-cart` text domain: ```php __( 'String', 'modern-cart' ) esc_html__( 'String', 'modern-cart' ) _n( 'singular', 'plural', $count, 'modern-cart' ) _x( 'String', 'context', 'modern-cart' ) ``` ```javascript import { __ } from '@wordpress/i18n'; __( 'String', 'modern-cart' ); ``` --- ## Pre-Commit Checklist Before every commit: ```bash # PHP composer format # Auto-fix code style composer lint # Verify no PHPCS violations remain composer phpstan # Static analysis must pass # JavaScript npm run lint-js:fix # Fix and verify JS npm run lint-css:fix # Fix and verify CSS # Verify build npm run build # Production build must succeed ``` --- ## Pull Request Guidelines 1. **Branch from `dev`** (or the current development branch) 2. **One feature/fix per PR** — keep changes focused 3. **Update the changelog** in `README.md` under the appropriate version 4. **Test the change manually** against the checklist in [Testing-Guide](Testing-Guide) 5. **No debug code** — no `console.log`, no `error_log`, no `var_dump` in PR code 6. **Settings changes** must update `Helper::get_defaults()` schema AND `Settings_Fields::get_fields()` 7. **New hooks** must follow naming convention: `moderncart_{description}` (actions) or `moderncart_{description}` (filters) 8. **New options** must be added to the sanitize schema in `Admin_Menu::sanitize_data()` --- ## Adding a New Setting When adding a new setting option: 1. **Add to `Helper::get_defaults()`** — define key, default value, and type (string/boolean/number/hex) 2. **Add to `Settings_Fields::get_fields()`** — define UI field (label, type, options, doc link) 3. **Use in PHP** — read via `$this->get_option('new_key', MODERNCART_SETTINGS, $default)` or `Helper::get_option(OPTION_GROUP)['new_key']` 4. **Add to sanitizer** — the schema-based sanitizer in `Admin_Menu::sanitize_data()` picks up the type automatically from `get_defaults()` 5. **Test** — verify the setting saves and loads correctly --- ## Adding a New Template 1. Create the PHP file in `templates/cart/` or `templates/shop/` 2. Use `moderncart_get_template_part()` to load it (supports theme overrides automatically) 3. Document available `$data` variables in the template file docblock 4. Register it in the [Template-System](Template-System) documentation --- ## Vendor Directory `vendor/` is committed to the repository for distribution (no Composer on production servers). After any `composer install` or `composer update`, commit the updated `vendor/` directory.