Skip to content

Commit 9f361c9

Browse files
dcalhoundcalhoun
committed
docs: remove redundant content from AGENTS.md
Remove information that is duplicated elsewhere in the project: - Detailed command listings (available via `make help`) - Architecture details (documented in `docs/code/architecture.md`) - Logging and lint guidelines (enforced by ESLint config) Consolidate remaining guidance and add Conventional Commits note to the pull request guidelines section.
1 parent be80a77 commit 9f361c9

1 file changed

Lines changed: 13 additions & 148 deletions

File tree

‎AGENTS.md‎

Lines changed: 13 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -4,171 +4,37 @@ This file provides guidance to AI agents when working with code in this reposito
44

55
## Overview
66

7-
GutenbergKit is an experimental Gutenberg block editor for native iOS and Android apps built with web technologies. It consists of:
7+
GutenbergKit is a Gutenberg block editor for native iOS and Android apps built with web technologies. It consists of:
88

99
- A React-based web editor using WordPress Gutenberg packages
1010
- Swift package for iOS integration
1111
- Kotlin library for Android integration
1212
- Native-to-web bridge for communication between platforms
1313

14-
The primary branch is `trunk` (not `main`).
14+
For deeper architectural context on specific subsystems, see the docs under `docs/code/` — including `architecture.md`, `plugins.md`, `preloading.md`, and others.
1515

1616
## Common Development Commands
1717

1818
**CRITICAL**: Always use `make` commands over underlying tool commands (`npm`, `swift`, `gradle`, etc.) when they exist. The Makefile provides convenient wrappers that handle dependencies and configuration automatically. However, when you need to pass specific arguments that a `make` target does not support — such as running Prettier on a single file, linting only changed files, or running a single test file — use the underlying tool directly.
1919

20-
To see all available make commands, run:
20+
To see all available make commands with descriptions, run:
2121

2222
```bash
2323
make help
24-
# or simply
25-
make
2624
```
2725

28-
This will display a list of all available targets with descriptions.
26+
By default, dependencies, translations, and JS build are skipped if output directories already exist. Environment variables be used to force refresh of these steps when needed.
2927

30-
### Web Development
28+
- `REFRESH_DEPS=1` - Force refresh of dependencies (e.g. re-install npm packages)
29+
- `REFRESH_L10N=1` - Force refresh of translations (e.g. re-run translation extraction)
30+
- `REFRESH_JS_BUILD=1` - Force refresh of JavaScript build (e.g. clear Vite cache)
3131

32-
```bash
33-
# Install dependencies
34-
npm ci
35-
36-
# Start development server (use this for active development)
37-
make dev-server
38-
39-
# Start standalone React DevTools server
40-
make dev-tools
41-
42-
# Preview production build locally
43-
make preview
44-
45-
# Run JavaScript tests (one-time run)
46-
make test-js
47-
48-
# Run JavaScript tests in watch mode (for active development)
49-
make test-js-watch
50-
51-
# Lint JavaScript code
52-
make lint-js
53-
54-
# Lint and auto-fix JavaScript code
55-
make lint-fix-js
56-
57-
# Format JavaScript code
58-
make format
59-
```
60-
61-
### Building
62-
63-
```bash
64-
# Build everything (web, iOS, Android)
65-
make build
32+
## Local WordPress Environment (wp-env)
6633

67-
# This builds the web app and copies assets to:
68-
# - ios/Sources/GutenbergKit/Gutenberg/
69-
# - android/Gutenberg/src/main/assets/
70-
71-
# By default, the build is skipped if output directories already exist
72-
# Force refresh of dependencies, translations, and JS build
73-
make build REFRESH_DEPS=1 REFRESH_L10N=1 REFRESH_JS_BUILD=1
74-
75-
# Clean build artifacts
76-
make clean
77-
```
78-
79-
### iOS Development
80-
81-
```bash
82-
# Build Swift package
83-
make build-swift-package
84-
85-
# Run Swift tests
86-
make test-swift-package
87-
```
88-
89-
### Android Development
90-
91-
```bash
92-
# Build Android library to local Maven
93-
make local-android-library
94-
95-
# Run Android tests
96-
make test-android
97-
```
98-
99-
### Local WordPress Environment (wp-env)
100-
101-
A local WordPress environment powered by `@wordpress/env` for testing the full editor experience with theme styles, media uploads, and plugin block assets.
102-
103-
```bash
104-
# Start the local WordPress environment (requires Docker)
105-
make wp-env-start
106-
107-
# Stop the environment (preserves data)
108-
make wp-env-stop
109-
110-
# Destroy the environment and remove all data
111-
make wp-env-clean
112-
113-
# View WordPress logs
114-
make wp-env-logs
115-
116-
# Run a WP-CLI command
117-
make wp-env-cli CMD="post list"
118-
```
34+
A local WordPress environment powered by `@wordpress/env` is available for verifying/testing changes against a full editor experience with theme styles, media uploads, and plugin block assets. Relevant commands are available via `make help`.
11935

12036
See `docs/code/local-wordpress.md` for detailed setup instructions and troubleshooting.
12137

122-
> **Note:** Most `make` targets have equivalent `npm` scripts in `package.json`. Build targets accept `REFRESH_DEPS=1`, `REFRESH_L10N=1`, and `REFRESH_JS_BUILD=1` flags to force refresh of dependencies, translations, and JavaScript builds respectively. Run `make help` for full details.
123-
124-
## Architecture
125-
126-
### Web Editor Structure
127-
128-
The web editor is built with React and WordPress packages:
129-
130-
- **Entry Points**:
131-
- `src/index.js` - Main editor entry point (supports plugins via bundled code)
132-
- **Core Components**:
133-
- `src/components/editor/` - Main editor component with host bridge integration
134-
- `src/components/visual-editor/` - Visual editing interface
135-
- `src/components/text-editor/` - HTML text editing interface
136-
- **Native Bridge**: `src/utils/bridge.js` - Handles communication between web and native platforms
137-
138-
### Native Integration
139-
140-
#### iOS (Swift)
141-
142-
- **Main Classes**:
143-
- `EditorViewController` - WebView container and bridge
144-
- `EditorConfiguration` - Editor settings and capabilities
145-
- `EditorService` - API communication layer
146-
- `GBWebView` - Custom WebView with editor-specific features
147-
148-
#### Android (Kotlin)
149-
150-
- **Main Classes**:
151-
- `GutenbergView` - WebView container and bridge
152-
- `EditorConfiguration` - Editor settings and capabilities
153-
- `GutenbergRequestInterceptor` - Handles API routing
154-
- `CachedAssetRequestInterceptor` - Asset caching layer
155-
156-
### Communication Pattern
157-
158-
The editor uses a bidirectional bridge pattern:
159-
160-
1. **Web → Native**: JavaScript calls methods on `window.editorDelegate` (Android) or `window.webkit.messageHandlers` (iOS)
161-
2. **Native → Web**: Native code evaluates JavaScript in the WebView
162-
3. **Message Types**: Editor loaded, content changed, media upload, block management, etc.
163-
164-
### Build System
165-
166-
- **Vite**: Handles web bundling and development server
167-
- **Translations**: Automated translation preparation from WordPress packages
168-
- **Asset Distribution**: Built assets are copied to platform-specific directories
169-
170-
> For deeper architectural context on specific subsystems, see the docs under `docs/code/` — including `architecture.md`, `plugins.md`, `preloading.md`, and others.
171-
17238
## Code Quality Standards
17339

17440
The project follows WordPress coding standards for JavaScript:
@@ -210,12 +76,13 @@ make lint-js-fix
21076

21177
These commands ensure code quality and prevent lint errors from blocking commits.
21278

213-
### Pull Request Guidelines
79+
### Commit and Pull Request Guidelines
21480

21581
When creating pull requests:
21682

21783
1. **Use the PR template**: Read `.github/PULL_REQUEST_TEMPLATE.md` to get the current template structure and follow it when writing the PR body.
21884
2. **Assign a label**: Use `gh label list` to retrieve available labels and select the most relevant one for the PR.
85+
3. **Use Conventional Commits**: Follow the Conventional Commits specification for commit messages (e.g. `feat: add new block type`, `fix: resolve toolbar bug`).
21986

22087
### E2E Test Interaction Guidelines
22188

@@ -230,8 +97,6 @@ Since GutenbergKit targets touch devices (iOS/Android), E2E tests should prefer
23097

23198
## Common Pitfalls
23299

233-
- **Do not edit build output directories.** The files under `ios/Sources/GutenbergKit/Gutenberg/` and `android/Gutenberg/src/main/assets/` are generated by `make build`. Never modify them directly — run `make build` to regenerate them instead.
234-
- **Do not use `console.*` directly.** Always use the logger utility (`src/utils/logger.js`). See the Logging Guidelines section above.
235-
- **Always run `make lint-fix-js` before committing.** Lint errors will block commits via pre-commit hooks.
100+
- **The primary branch is `trunk` (not `main`).** Always ensure you are working on the `trunk` branch for development and pull requests. The `main` branch is not used in this repository.
101+
- **Do not edit build output directories.** The files under `dist/`, `ios/Sources/GutenbergKit/Gutenberg/`, and `android/Gutenberg/src/main/assets/` are generated by `make build`. Never modify them directly — run `make build` to regenerate them instead.
236102
- **Patching dependencies: modify `node_modules`, then run `npx patch-package <package-name>`.** Do not edit the `.patch` files under `patches/` by hand. The workflow is: make changes in `node_modules/<package>`, verify they work, then run `npx patch-package <package-name>` to create or update the patch file. Document the patch and its justification in `patches/README.md`.
237-
- **Do not edit the `dist/` directory.** It is a build artifact generated by Vite. Run `make build` or `make dev-server` instead.

0 commit comments

Comments
 (0)