elementor / CONTRIBUTING.md

CONTRIBUTING.md in Elementor Website Builder – more than just a page builder 4.2.2, at CONTRIBUTING.md

207 lines 4.7 KB

Raw Download Zip

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 instal
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