Common Pitfalls

// ❌ BAD: Generic compat directory
/lib/compat/my-feature.php

// ✅ GOOD: WordPress version-specific
/lib/compat/wordpress-6.4/my-feature.php

// ❌ BAD in a bundled package
import { __experimentalUseColors } from '@wordpress/block-editor';

// ✅ GOOD: Use stable, public APIs
import { useColors } from '@wordpress/block-editor';

// ❌ BAD in @wordpress/block-editor
import { useEntityProp } from '@wordpress/core-data';
import apiFetch from '@wordpress/api-fetch';

function MyComponent() {
  const [title] = useEntityProp('postType', 'post', 'title');
  // ...
}

// ✅ GOOD: Accept data via props
function MyComponent({ title, onTitleChange }) {
  // Component stays agnostic
  // Higher layers (editor/edit-post) provide the data
}

// ❌ BAD: Gutenberg-specific check
if (projectName === 'gutenberg') {
  // Special webpack config
}

// ✅ GOOD: Make it configurable
if (config.enableExperimentalFeatures) {
  // Feature enabled via configuration
}

# Ensure tests pass before submitting PR
npm test
npm run test:php

// ❌ BAD: Testing source function
public function test_my_function() {
    $result = block_core_my_block_render($args);
    $this->assertEquals($expected, $result);
}

// ✅ GOOD: Testing built function
public function test_my_function() {
    $result = gutenberg_block_core_my_block_render($args);
    $this->assertEquals($expected, $result);
}

# Fix formatting issues
npm run format

# Check for linting issues
npm run lint:js
npm run lint:php

# Auto-fix PHP standards
vendor/bin/phpcbf

# Test the build
npm run build

# Run all checks
npm test
npm run lint:js
npm run lint:php

// If you rename in: block-editor/src/components/toolbar.js
// Also update: block-editor/src/components/toolbar.native.js

// ❌ BAD: Desktop renamed, mobile not updated
// toolbar.js
export function BlockToolbar() { /* ... */ }

// toolbar.native.js (outdated)
export function Toolbar() { /* ... */ }

// ✅ GOOD: Both synchronized
// toolbar.js
export function BlockToolbar() { /* ... */ }

// toolbar.native.js
export function BlockToolbar() { /* ... */ }

import deprecated from '@wordpress/deprecated';

export function oldFunction() {
  deprecated('oldFunction', {
    since: '10.3',
    plugin: 'Gutenberg',
    alternative: 'newFunction',
  });

  return newFunction();
}

export function newFunction() {
  // New implementation
}

const deprecated = [
  {
    attributes: { /* old attributes */ },
    save({ attributes }) {
      // Old save function
    },
  },
];

export default {
  // Current block definition
  deprecated,
};

# ❌ BAD commit message
git commit -m "fixes"

# ✅ GOOD commit message
git commit -m "Fix block toolbar alignment in nested blocks"

# Check status first
npm run wp-env status

# Start if not running
npm run wp-env start

# Then run tests
npm run test:e2e
npm run test:php