elementor
Last commit date
app
4 months ago
assets
4 months ago
core
4 months ago
data
7 months ago
includes
4 months ago
modules
4 months ago
vendor
4 months ago
vendor_prefixed
8 months ago
CONTRIBUTING.md
9 months ago
changelog.txt
4 months ago
elementor.php
4 months ago
license.txt
3 years ago
readme.txt
4 months ago
CONTRIBUTING.md
207 lines
| 1 | # Contributing |
| 2 | |
| 3 | A guide on how to get started contributing code to the Elementor plugin. |
| 4 | |
| 5 | Before diving into this repository, make sure you have a basic understanding of Elementor and its architecture. |
| 6 | |
| 7 | ## Architecture |
| 8 | If you are interested in learning more about the architecture of Elementor, please refer to the documentation in the `docs/` directory. |
| 9 | |
| 10 | ## Repository structure |
| 11 | |
| 12 | The repository is structured as follows: |
| 13 | |
| 14 | ``` |
| 15 | @/elementor |
| 16 | ├── app/ |
| 17 | │ ├── admin-menu-items/ |
| 18 | │ ├── assets/ |
| 19 | │ │ ├── js/ |
| 20 | │ │ └── styles/ |
| 21 | │ ├── modules/ |
| 22 | │ │ ├── import-export/ |
| 23 | │ │ ├── kit-library/ |
| 24 | │ │ ├── onboarding/ |
| 25 | │ │ └── site-editor/ |
| 26 | │ ├── app.php |
| 27 | │ └── view.php |
| 28 | ├── core/ |
| 29 | │ ├── admin/ |
| 30 | │ ├── base/ |
| 31 | │ ├── editor/ |
| 32 | │ ├── frontend/ |
| 33 | │ ├── settings/ |
| 34 | │ ├── utils/ |
| 35 | │ └── ... |
| 36 | ├── includes/ |
| 37 | │ ├── controls/ |
| 38 | │ ├── widgets/ |
| 39 | │ ├── managers/ |
| 40 | │ └── ... |
| 41 | ├── modules/ (Feature modules) |
| 42 | │ ├── ai/ |
| 43 | │ ├── atomic-widgets/ |
| 44 | │ ├── floating-buttons/ |
| 45 | │ ├── global-classes/ |
| 46 | │ ├── nested-elements/ |
| 47 | │ └── ... |
| 48 | ├── assets/ (Static assets) |
| 49 | │ ├── css/ |
| 50 | │ ├── js/ |
| 51 | │ ├── images/ |
| 52 | │ └── lib/ |
| 53 | ├── packages/ (V4 packages) |
| 54 | │ ├── packages/ |
| 55 | │ ├── tests/ |
| 56 | │ └── package.json |
| 57 | ├── tests/ (Test suites) |
| 58 | │ ├── playwright/ |
| 59 | │ ├── phpunit/ |
| 60 | │ ├── jest/ |
| 61 | │ └── qunit/ |
| 62 | ├── docs/ (Documentation) |
| 63 | ├── elementor.php (Main plugin file) |
| 64 | ├── package.json |
| 65 | └── composer.json |
| 66 | ``` |
| 67 | |
| 68 | ## Development Setup |
| 69 | |
| 70 | To get started with development: |
| 71 | |
| 72 | 1. Clone the repository |
| 73 | 2. Install dependencies: |
| 74 | ```bash |
| 75 | npm run prepare-environment |
| 76 | ``` |
| 77 | |
| 78 | 3. Start development: |
| 79 | ```bash |
| 80 | npm run watch |
| 81 | ``` |
| 82 | |
| 83 | This will start the development environment with file watching enabled. |
| 84 | |
| 85 | ## Test, Lint & Build |
| 86 | |
| 87 | ### Testing |
| 88 | |
| 89 | To run PHP tests: |
| 90 | ```bash |
| 91 | npm run test:php |
| 92 | ``` |
| 93 | |
| 94 | To run JavaScript tests: |
| 95 | ```bash |
| 96 | npm run test:jest |
| 97 | ``` |
| 98 | |
| 99 | To run Playwright end-to-end tests: |
| 100 | ```bash |
| 101 | npm run start-local-server |
| 102 | npm run test:playwright |
| 103 | or |
| 104 | npm run test:playwright:* |
| 105 | ``` |
| 106 | |
| 107 | ### Linting |
| 108 | |
| 109 | You can run the linter by executing: |
| 110 | ```bash |
| 111 | npm run lint |
| 112 | ``` |
| 113 | |
| 114 | This command uses ESLint for JavaScript/TypeScript files and includes package linting. |
| 115 | |
| 116 | ### Building |
| 117 | |
| 118 | To build the project for production: |
| 119 | ```bash |
| 120 | npm run build |
| 121 | ``` |
| 122 | |
| 123 | For development builds: |
| 124 | ```bash |
| 125 | npm run start |
| 126 | ``` |
| 127 | |
| 128 | To build packages: |
| 129 | ```bash |
| 130 | npm run build:packages |
| 131 | ``` |
| 132 | |
| 133 | ## Development Commands |
| 134 | |
| 135 | - `npm run start` - Full build and setup (dev mode) |
| 136 | - `npm run watch` - Start development with file watching |
| 137 | - `npm run scripts` - Build JavaScript assets |
| 138 | - `npm run scripts:watch` - Watch JavaScript files |
| 139 | - `npm run styles` - Build CSS assets |
| 140 | - `npm run styles:watch` - Watch CSS files |
| 141 | - `npm run build:packages` - Build frontend packages |
| 142 | - `npm run build:tools` - Build development tools |
| 143 | |
| 144 | ## Testing Environment Setup |
| 145 | |
| 146 | To set up the testing environment: |
| 147 | ```bash |
| 148 | npm run setup:testing |
| 149 | ``` |
| 150 | |
| 151 | To restart the testing environment: |
| 152 | ```bash |
| 153 | npm run restart:testing |
| 154 | ``` |
| 155 | |
| 156 | ## Commit message conventions |
| 157 | |
| 158 | This repository uses [](https://www.conventionalcommits.org/en/v1.0.0/Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/](https://www.conventionalcommits.org/en/v1.0.0/), so please make sure to follow this convention to keep consistency in the repository. |
| 159 | |
| 160 | ## Pull requests |
| 161 | |
| 162 | Maintainers merge pull requests by squashing all commits and editing the commit message if necessary using the GitHub user interface. |
| 163 | |
| 164 | Ensure you choose an appropriate commit message, and exercise caution when dealing with changes that may disrupt existing functionality. |
| 165 | |
| 166 | Additionally, remember to include tests for your modifications to ensure comprehensive coverage and maintain code quality. |
| 167 | |
| 168 | ## Working with Packages |
| 169 | |
| 170 | The `packages/` directory contains frontend packages that can be developed separately: |
| 171 | |
| 172 | 1. Navigate to the packages directory: |
| 173 | ```bash |
| 174 | cd packages |
| 175 | ``` |
| 176 | |
| 177 | 2. Install dependencies: |
| 178 | ```bash |
| 179 | npm ci |
| 180 | ``` |
| 181 | |
| 182 | 3. Start development: |
| 183 | ```bash |
| 184 | npm run dev |
| 185 | ``` |
| 186 | |
| 187 | When working on the main plugin with packages, use: |
| 188 | ```bash |
| 189 | npm run watch |
| 190 | ``` |
| 191 | |
| 192 | This will automatically handle package building and watching. |
| 193 | |
| 194 | ## Code Quality |
| 195 | |
| 196 | - Follow WordPress coding standards |
| 197 | - Use meaningful commit messages |
| 198 | - Write tests for new features |
| 199 | - Update documentation when needed |
| 200 | - Ensure backward compatibility when possible |
| 201 | |
| 202 | ## Getting Help |
| 203 | |
| 204 | - Check the `docs/` directory for detailed documentation |
| 205 | - Review existing code for patterns and conventions |
| 206 | - Ask questions in pull requests for clarification |
| 207 |