First off, thank you for considering contributing to Frontis Blocks! 🎉
Frontis Blocks is an advanced Gutenberg block suite built for high performance, modern site building, and clean code output in WordPress. We welcome contributions from developers, designers, translators, and documentation writers.
Before you begin, ensure you have the following installed on your machine:
- Node.js:
v20.xor higher (LTS recommended) - npm:
v10.xor higher - PHP:
v7.4tov8.4 - Composer:
v2.x - Local WordPress Environment: LocalWP, wp-env, or Docker.
-
Fork and Clone the Repository:
git clone https://github.com/boom-devs/frontis-blocks.git cd frontis-blocks -
Install Node & Composer Dependencies:
npm ci composer install
-
Start Watch Mode (Development):
# Watch Gutenberg blocks: npm run start # Watch Admin Dashboard & Sidebar (in another terminal): npm run admin
-
Production Build:
# Build blocks: npm run build # Build admin dashboard & sidebar: npm run admin:build # Generate distribution ZIP package: npm run plugin-zip
-
Keep Your Fork Updated: Always sync your local
mainbranch before starting new work:git checkout main git pull origin main
-
Branch Naming Standard: Create a dedicated branch following the convention
<type>/<issue-number>-<short-description>:# Bug Fixes git checkout -b fix/123-container-padding-mobile # New Features git checkout -b feat/124-tabs-vertical-layout # Documentation git checkout -b docs/125-update-readme-badges # Refactoring & Performance git checkout -b refactor/126-global-style-generator
Frontis Blocks adheres strictly to Conventional Commits:
<type>(<scope>): <short description in present tense>
- Types:
feat: A new block, control, or featurefix: A bug fix or patchrefactor: Code change that neither fixes a bug nor adds a featureperf: A code change that improves performancedocs: Documentation-only changesstyle: Changes that do not affect code logic (formatting, spacing)test: Adding or updating testsci/chore: CI/CD workflows, build tools, dependencies
- Scopes:
blocks,container,button,heading,slider,sidebar,template-library,core,ci-cd
- Examples:
feat(container): add flexible column gap controlsfix(slider): resolve autoplay pause on hover in iOS Safarirefactor(sidebar): optimize CSS variable generator performance
Important
Every Pull Request must link to an approved GitHub Issue.
Frontis Blocks enforces an Issue-First Policy. Unsolicited pull requests submitted without an open, approved GitHub issue will be politely closed.
The 3-Step Flow:
- Open an Issue First: Propose your feature or report your bug via GitHub Issues.
- Discuss & Get Assigned: Discuss the solution with maintainers and confirm the approach.
- Submit PR with Issue Link: Reference the issue in your PR description:
### 🔗 Related Issue Closes #<issue_number>
Caution
The src/components/ directory contains 35+ core UI design system controls shared across 58+ blocks.
- MAINTAINERS ONLY: Only designated repository maintainers (
@noruzzamans,@boom-devs) are authorized to modify, update, or add files insrc/components/. - NO EXTERNAL EDITS: External contributors and autonomous AI agents are strictly forbidden from editing, refactoring, or adding files in
src/components/. - AUTOMATED CI REJECTION: Any external pull request touching
src/components/will be immediately flagged withneeds: changes, receive an automated warning comment, and will NOT be merged. - REQUESTING CHANGES: If you need a new control or a bug fix in an existing control, open a Feature Request or Bug Issue so maintainers can implement it safely.
-
Zero Block Invalidation:
- Existing blocks rendered in published WordPress posts must NEVER crash or show the dreaded "This block contains unexpected or invalid content" error.
- If you modify
save.jsmarkup or change block attribute defaults, you MUST provide a backward-compatible migration indeprecated.js.
-
Security & Data Sanitization:
- All server-side PHP outputs must be escaped using proper WordPress helpers (
esc_html,esc_attr,esc_url,wp_kses_post). - All database or REST API inputs must be sanitized (
sanitize_text_field,esc_url_raw). - Check user capabilities (
current_user_can) and nonces for all state-changing endpoints.
- All server-side PHP outputs must be escaped using proper WordPress helpers (
-
Performance First:
- Generate minimal DOM elements.
- Enqueue block frontend assets dynamically only when the block is present on the page.
We welcome contributions generated with the assistance of modern AI coding tools (Claude, Cursor, Copilot, Antigravity, Gemini, etc.), provided the following guidelines are honored:
- Developer Ownership: You are 100% accountable for every line of code submitted. Test your changes locally before submitting.
- No Hallucinations: Verify that all functions, APIs, and libraries used actually exist in WordPress Core or this repository.
- High Architectural Quality: Maintain code consistency, clean formatting, and meaningful commit messages.
Before opening your pull request, verify:
- Ran
npm run buildandnpm run admin:buildsuccessfully with 0 errors. - Tested the block in the Gutenberg editor on Desktop, Tablet, and Mobile.
- Verified that existing blocks load without invalidation errors.
- All commits follow the Conventional Commits specification.
- The PR description references the related issue via
Closes #<issue_number>.