github/electron
1
1
Fork 0
mirror of https://github.com/electron/electron.git synced 2026-01-05 05:34:14 -05:00
Code Issues Packages Projects Releases Wiki Activity

chore: add CLAUDE.md and Chromium Upgrade claude skill (#49229)

Browse Source 
* chore: add CLAUDE.md and Chromium Upgrade claude skill

* Update script/lint.js

Co-authored-by: David Sanders <dsanders11@ucsbalum.com>

---------

Co-authored-by: David Sanders <dsanders11@ucsbalum.com>
This commit is contained in:
Samuel Attard
2025-12-19 13:07:58 +13:00
committed by GitHub
parent a90ccc753b
commit 7433c14af5
8 changed files with 654 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.claude/.gitignore vendored Normal file
View File

@@ -0,0 +1 @@
settings.local.json

24
.claude/settings.json Normal file
View File

@@ -0,0 +1,24 @@
{
"permissions": {
"allow": [
"Bash(e sync)",
"Bash(e patches --list-targets:*)",
"Bash(git add:*)",
"Bash(git am:*)",
"Bash(git commit:*)",
"Bash(git log:*)",
"Bash(git show:*)",
"Bash(e patches:*)",
"Bash(e sync:*)",
"Skill(electron-chromium-upgrade)",
"Read(*)",
"Bash(echo:*)",
"Bash(e build:*)",
"Bash(tee:*)",
"Bash(git diff:*)",
"Bash(git rev-parse:*)"
],
"deny": [],
"ask": []
}
}

199
.claude/skills/electron-chromium-upgrade/SKILL.md Normal file
View File

@@ -0,0 +1,199 @@
---
name: electron-chromium-upgrade
description: Guide for performing Chromium version upgrades in the Electron project. Use when working on the roller/chromium/main branch to fix patch conflicts during `e sync --3`. Covers the patch application workflow, conflict resolution, analyzing upstream Chromium changes, and proper commit formatting for patch fixes.
---
# Electron Chromium Upgrade: Phase One
## Summary
Run `e sync --3` repeatedly, fixing patch conflicts as they arise, until it succeeds. Then run `e patches all` and commit changes atomically.
## Success Criteria
Phase One is complete when:
- `e sync --3` exits with code 0 (no patch failures)
- `e patches all` has been run to export all changes
- All changes are committed per the commit guidelines below
Do not stop until these criteria are met.
**CRITICAL** Do not delete or skip patches unless 100% certain the patch is no longer needed. Complicated conflicts or hard to resolve issues should be presented to the user after you have exhausted all other options. Do not delete the patch just because you can't solve it.
## Context
The `roller/chromium/main` branch is created by automation to update Electron's Chromium dependency SHA. No work has been done to handle breaking changes between the old and new versions.
**Key directories:**
- Current directory: Electron repo (always run `e` commands here)
- `..` (parent): Chromium repo (where most patches apply)
- `patches/`: Patch files organized by target
- `docs/development/patches.md`: Patch system documentation
## Workflow
1. Delete the `.git/rr-cache` in both the `electron` and `..` folder to ensure no accidental rerere replays occur from before this upgrade phase attempt started
2. Run `e sync --3` (the `--3` flag enables 3-way merge, always required)
3. If succeeds → skip to step 6
4. If patch fails:
- Identify target repo and patch from error output
- Analyze failure (see references/patch-analysis.md)
- Fix conflict in target repo's working directory
- Run `git am --continue` in affected repo
- Repeat until all patches for that repo apply
- IMPORTANT: Once `git am --continue` succeeds you MUST run `e patches {target}` to export fixes
- Return to step 1
5. When `e sync --3` succeeds, run `e patches all`
6. **Read `references/phase-one-commit-guidelines.md` NOW**, then commit changes following those instructions exactly.
Before committing any Phase One changes, you MUST read `references/phase-one-commit-guidelines.md` and follow its instructions exactly.
## Commands Reference
| Command | Purpose |
|---------|---------|
| `e sync --3` | Clone deps and apply patches with 3-way merge |
| `git am --continue` | Continue after resolving conflict (run in target repo) |
| `e patches {target}` | Export commits from target repo to patch files |
| `e patches all` | Export all patches from all targets |
| `e patches --list-targets` | List targets and config paths |
## Patch System Mental Model
```
patches/{target}/*.patch → [e sync --3] → target repo commits
← [e patches] ←
```
## When to Edit Patches
| Situation | Action |
|-----------|--------|
| During active `git am` conflict | Fix in target repo, then `git am --continue` |
| Modifying patch outside conflict | Edit `.patch` file directly |
| Creating new patch (rare, avoid) | Commit in target repo, then `e patches {target}` |
Fix existing patches 99% of the time rather than creating new ones.
## Patch Fixing Rules
1. **Preserve authorship**: Keep original author in TODO comments (from patch `From:` field)
2. **Never change TODO assignees**: `TODO(name)` must retain original name
3. **Update descriptions**: If upstream changed (e.g., `DCHECK` → `CHECK_IS_TEST`), update patch commit message to reflect current state
## Final Deliverable
After Phase One, write a summary of every change: what was fixed, why, reasoning, and Chromium CL links.
# Electron Chromium Upgrade: Phase Two
## Summary
Run `e build -k 999` repeatedly, fixing build issues as they arise, until it succeeds. Then run `e start --version` to validate Electron launches and commit changes atomically.
Run Phase Two immediately after Phase One is complete.
## Success Criteria
Phase Two is complete when:
- `e build -k 999` exits with code 0 (no build failures)
- `e start --version` has been run to check Electron launches
- All changes are committed per the commit guidelines below
Do not stop until these criteria are met. Do not delete code or features, never comment out code in order to take short cut. Make all existing code, logic and intention work.
## Context
The `roller/chromium/main` branch is created by automation to update Electron's Chromium dependency SHA. No work has been done to handle breaking changes between the old and new versions. Chromium APIs frequently are renamed or refactored. In every case the code in Electron must be updated to account for the change in Chromium, strongly avoid making changes to the code in chromium to fix Electrons build.
**Key directories:**
- Current directory: Electron repo (always run `e` commands here)
- `..` (parent): Chromium repo (do not touch this code to fix build issues, just read it to obtain context)
## Workflow
1. Run `e build -k 999` (the `-k 999` flag is a flag to ninja to say "do not stop until you find that many errors" it is an attempt to get as much error
context as possible for each time we run build)
2. If succeeds → skip to step 6
3. If build fails:
- Identify underlying file in "electron" from the compilation error message
- Analyze failure
- Fix build issue by adapting Electron's code for the change in Chromium
- Run `e build -t {target_that_failed}.o` to build just the failed target we were specifically fixing
- You can identify the target_that_failed from the failure line in the build log. E.g. `FAILED: 2e506007-8d5d-4f38-bdd1-b5cd77999a77 "./obj/electron/chromium_src/chrome/process_singleton_posix.o" CXX obj/electron/chromium_src/chrome/process_singleton_posix.o` the target name is `obj/electron/chromium_src/chrome/process_singleton_posix.o`
- **Read `references/phase-two-commit-guidelines.md` NOW**, then commit changes following those instructions exactly.
- Return to step 1
4. **CRITICAL**: After ANY commit (especially patch commits), immediately run `git status` in the electron repo
- Look for other modified `.patch` files that only have index/hunk header changes
- These are dependent patches affected by your fix
- Commit them immediately with: `git commit -am "chore: update patch hunk headers"`
- This prevents losing track of necessary updates
5. Return to step 1
6. When `e build` succeeds, run `e start --version`
7. Check if you have any pending changes in the Chromium repo by running `git status`
- If you have changes follow the instructions below in "A. Patch Fixes" to correctly commit those modifications into the appropriate patch file
Before committing any Phase Two changes, you MUST read `references/phase-two-commit-guidelines.md` and follow its instructions exactly.
## Build Error Detection
When monitoring `e build -k 999` output, filter for errors using this regex pattern:
error:|FAILED:|fatal:|subcommand failed|build finished
The build output is extremely verbose. Filtering is essential to catch errors quickly.
## Commands Reference
| Command | Purpose |
|---------|---------|
| `e build -k 999` | Builds Electron and won't stop until either all targets attempted or 999 errors found |
| `e build -t {target}.o` | Build just one specific target to verify a fix |
| `e start --version` | Validate Electron launches after successful build |
## Two Types of Build Fixes
### A. Patch Fixes (for files in chromium_src or patched Chromium files)
When the error is in a file that Electron patches (check with `grep -l "filename" patches/chromium/*.patch`):
1. Edit the file in the Chromium source tree (e.g., `/src/chrome/browser/...`)
2. Create a fixup commit targeting the original patch commit:
```bash
cd .. # to chromium repo
git add <modified-file>
git commit --fixup=<original-patch-commit-hash>
GIT_SEQUENCE_EDITOR=: git rebase --autosquash --autostash -i <commit>^
3. Export the updated patch: e patches chromium
4. Commit the updated patch file in the electron repo following the `references/phase-one-commit-guidelines.md`, then commit changes following those instructions exactly. **READ THESE GUIDELINES BEFORE COMMITTING THESE CHANGES**
To find the original patch commit to fixup: `git log --oneline | grep -i "keyword from patch name"`
The base commit for rebase is the Chromium commit before patches were applied. Find it by checking the `refs/patches/upstream-head` ref.
B. Electron Code Fixes (for files in shell/, electron/, etc.)
When the error is in Electron's own source code:
1. Edit files directly in the electron repo
2. Commit directly (no patch export needed)
Dependent Patch Updates
IMPORTANT: When you modify a patch, other patches that apply to the same file may have their hunk headers invalidated. After committing a patch fix:
1. Run git status in the electron repo
2. Look for other modified .patch files with just index/hunk header changes
3. Commit these with: git commit -m "chore: update patch hunk headers"
# Critical: Read Before Committing
- Before ANY Phase One commits: Read `references/phase-one-commit-guidelines.md`
- Before ANY Phase Two commits: Read `references/phase-two-commit-guidelines.md`
# Skill Directory Structure
This skill has additional reference files in `references/`:
- patch-analysis.md - How to analyze patch failures
- phase-one-commit-guidelines.md - Commit format for Phase One
- phase-two-commit-guidelines.md - Commit format for Phase Two
Read these when referenced in the workflow steps.

69
.claude/skills/electron-chromium-upgrade/references/patch-analysis.md Normal file
View File

@@ -0,0 +1,69 @@
# Analyzing Patch Failures
## Investigation Steps
1. **Read the patch file** at `patches/{target}/{patch_name}.patch`
2. **Examine current state** of the file in Chromium at mentioned line numbers
3. **Check recent upstream changes:**
```bash
cd .. # or relevant target repo
git log --oneline -10 -- {file}
```
4. **Find Chromium CL** in commit messages:
```
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/{CL_NUMBER}
```
## Common Failure Patterns
| Pattern | Cause | Solution |
|---------|-------|----------|
| Context lines don't match | Surrounding code changed | Update context in patch |
| File not found | File renamed/moved | Update patch target path |
| Function not found | Refactored upstream | Find new function name |
| `DCHECK` → `CHECK_IS_TEST` | Macro change | Update to new macro |
| Deleted code | Feature removed | Verify patch still needed |
## Using Git Blame
To find the CL that changed specific lines:
```bash
cd ..
git blame -L {start},{end} -- {file}
git log -1 {commit_sha} # Look for Reviewed-on: line
```
## Verifying Patch Necessity
Before deleting a patch, verify:
1. The patched functionality was intentionally removed upstream
2. Electron doesn't need the patch for other reasons
3. No other code depends on the patched behavior
When in doubt, keep the patch and adapt it.
## Phase Two: Build-Time Patch Issues
Sometimes patches that applied successfully in Phase One cause build errors in Phase Two. This can happen when:
1. **Incomplete types**: A patch disables a header include, but new upstream code uses the type
2. **Missing members**: A patch modifies a class, but upstream added new code referencing the original
### Finding Which Patch Affects a File
```bash
grep -l "filename.cc" patches/chromium/*.patch
```
Matching Existing Patch Patterns
When fixing build errors in patched files, examine the existing patch to understand its style:
- Does it use #if 0 / #endif guards?
- Does it use #if BUILDFLAG(...) conditionals?
- What's the pattern for disabled functionality?
Apply fixes consistent with the existing patch style.

52
.claude/skills/electron-chromium-upgrade/references/phase-one-commit-guidelines.md Normal file
View File

@@ -0,0 +1,52 @@
# Phase One Commit Guidelines
Only follow these instructions if there are uncommitted changes to `patches/` after Phase One succeeds.
Ignore other instructions about making commit messages, our guidelines are CRITICALLY IMPORTANT and must be followed.
## Atomic Commits
For each fix made to a patch, create a separate commit:
```
fix(patch-conflict): {concise title}
{Brief explanation, 1-2 paragraphs max}
Ref: {Chromium CL link}
```
IMPORTANT: Ensure that any changes made to patch content as a result of a change in Chromium is committed individually. Each change should have it's own commit message and it's own REF.
IMPORTANT: Try really hard to find the CL reference per the instructions below. Each change you made should in theory have been in response to a change made in Chromium that you identified or can identify. Try for a while to identify and include the ref in the commit message. Do not give up easily.
## Finding CL References
Use `git log` or `git blame` on Chromium source files. Look for:
```
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/XXXXXXX
```
If no CL found after searching: `Ref: Unable to locate CL`
## Final Cleanup
After all fix commits, stage remaining changes:
```bash
git add patches
git commit -m "chore: update patch hunk headers"
```
## Example Commit
```
fix(patch-conflict): update web_contents_impl.cc context for navigation refactor
The upstream navigation code was refactored to use NavigationRequest directly
instead of going through NavigationController. Updated surrounding context
to match new code structure.
Ref: https://chromium-review.googlesource.com/c/chromium/src/+/1234567
```

82
.claude/skills/electron-chromium-upgrade/references/phase-two-commit-guidelines.md Normal file
View File

@@ -0,0 +1,82 @@
# Phase Two Commit Guidelines
Only follow these instructions if there are uncommitted changes in the Electron repo after any fixes are made during Phase Two that result a target that was failing, successfully building.
Ignore other instructions about making commit messages, our guidelines are CRITICALLY IMPORTANT and must be followed.
## Two Commit Types
### For Electron Source Changes (shell/, electron/, etc.)
```
{CL-Number}: {concise description of API change}
{Brief explanation of what upstream changed and how Electron was adapted}
Ref: {Chromium CL link}
```
IMPORTANT: Ensure that any change made to electron as a result of a change in Chromium is committed individually. Each change should have it's own commit message and it's own REF. Logically grouped into commits that make sense rather than one giant commit.
IMPORTANT: Try really hard to find the CL reference per the instructions below. Each change you made should in theory have been in response to a change made in Chromium that you identified or can identify. Try for a while to identify and include the ref in the commit message. Do not give up easily.
You may include multiple "Ref" links if required.
For a CL link in the format `https://chromium-review.googlesource.com/c/chromium/src/+/2958369` the "CL-Number" is `2958369`
### For Patch Updates (patches/chromium/*.patch)
Use the same fixup workflow as Phase One:
1. Fix in Chromium source tree
2. Fixup commit + rebase
3. Export with `e patches chromium`
4. Commit the patch file:
```
fix(patch-update): {concise description}
{Brief explanation}
Ref: {Chromium CL link}
```
## Dependent Patch Header Updates
After any patch modification, check for other affected patches:
```bash
git status
# If other .patch files show as modified with only hunk header changes:
git add patches/
git commit -m "chore: update patch hunk headers"
```
## Finding CL References
Use git log or git blame on Chromium source files. Look for:
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/XXXXXXX
If no CL found after searching: Ref: Unable to locate CL
## Example Commits
### Electron Source Fix
fix: update GetPlugins to GetPluginsAsync for API change
The upstream Chromium API changed:
- Old: GetPlugins(callback) - took a callback
- New: GetPluginsAsync(callback) - async version takes a callback
Ref: https://chromium-review.googlesource.com/c/chromium/src/+/1234567
### Patch Fix
fix(patch-conflict): update picture-in-picture for gesture handling refactor
Upstream added new gesture handling code that accesses live caption dialog.
The live caption functionality is disabled in Electron's patch, so wrapped
the new code in #if 0 guards to match existing pattern.
Ref: https://chromium-review.googlesource.com/c/chromium/src/+/7654321

226
CLAUDE.md Normal file
View File

@@ -0,0 +1,226 @@
# Electron Development Guide
## Project Overview
Electron is a framework for building cross-platform desktop applications using web technologies. It embeds Chromium for rendering and Node.js for backend functionality.
## Directory Structure
```text
electron/ # This repo (run `e` commands here)
├── shell/ # Core C++ application code
│ ├── browser/ # Main process implementation (107+ API modules)
│ ├── renderer/ # Renderer process code
│ ├── common/ # Shared code between processes
│ ├── app/ # Application entry points
│ └── services/ # Node.js service integration
├── lib/ # TypeScript/JavaScript library code
│ ├── browser/ # Main process JS (47 API implementations)
│ ├── renderer/ # Renderer process JS
│ └── common/ # Shared JS modules
├── patches/ # Patches for upstream dependencies
│ ├── chromium/ # ~159 patches to Chromium
│ ├── node/ # ~48 patches to Node.js
│ └── ... # Other targets (v8, boringssl, etc.)
├── spec/ # Test suite (1189+ TypeScript test files)
├── docs/ # API documentation and guides
├── build/ # Build configuration
├── script/ # Build and automation scripts
└── chromium_src/ # Chromium source overrides
../ # Parent directory is Chromium source
```
## Build Tools Setup
Electron uses `@electron/build-tools` for development. The `e` command is the primary CLI.
**Installation:**
```bash
npm i -g @electron/build-tools
```
**Configuration location:** `~/.electron_build_tools/configs/`
## Essential Commands
### Configuration Management
| Command | Purpose |
|---------|---------|
| `e init <name> --root=<path> --bootstrap testing` | Create new build config and sync |
| `e use <name>` | Switch to a different build configuration |
| `e show current` | Display active configuration name |
| `e show configs` | List all available configurations |
### Build & Development Loop
| Command | Purpose |
|---------|---------|
| `e sync` | Fetch/update all source code and apply patches |
| `e sync --3` | Sync with 3-way merge (required for Chromium upgrades) |
| `e build` | Build Electron (runs GN + Ninja) |
| `e build -k 999` | Build and continue on errors (up to 999) |
| `e build -t <target>` | Build specific target (e.g., `electron:node_headers`) |
| `e start` | Run the built Electron executable |
| `e start --version` | Verify Electron launches and print version |
| `e test` | Run the test suite |
| `e debug` | Run Electron in debugger (lldb on macOS, gdb on Linux) |
### Patch Management
| Command | Purpose |
|---------|---------|
| `e patches <target>` | Export patches for a target (chromium, node, v8, etc.) |
| `e patches all` | Export all patches from all targets |
| `e patches --list-targets` | List available patch targets |
## Typical Development Workflow
```bash
# 1. Ensure you're on the right config
e show current
# 2. Sync to get latest code
e sync
# 3. Make your changes in shell/ or lib/ or ../
# 4. Build
e build
# 5. Test your changes (Leave the user to do this, don't run these commands unless asked)
e start
e test
# 6. If you modified patched files in Chromium:
cd .. # Go to Chromium repo
git add <files>
git commit -m "description of change"
cd electron
e patches chromium # Export the patch
```
## Patches System
Electron patches upstream dependencies (Chromium, Node.js, V8, etc.) to add features or modify behavior.
**How patches work:**
```text
patches/{target}/*.patch → [e sync --3] → target repo commits
← [e patches] ←
```
**Patch configuration:** `patches/config.json` maps patch directories to target repos.
**Key rules:**
- Fix existing patches 99% of the time rather than creating new ones
- Preserve original authorship in TODO comments
- Never change TODO assignees (`TODO(name)` must retain original name)
- Each patch file includes commit message explaining its purpose
**Creating/modifying patches:**
1. Make changes in the target repo (e.g., `../` for Chromium)
2. Create a git commit
3. Run `e patches <target>` to export
## Testing
**Test location:** `spec/` directory
**Running tests:**
```bash
e test # Run full test suite
```
**Test frameworks:** Mocha, Chai, Sinon
## Build Configuration
**GN build arguments:** Located in `build/args/`:
- `testing.gn` - Debug/testing builds
- `release.gn` - Release builds
- `all.gn` - Common arguments for all builds
**Main build file:** `BUILD.gn`
**Feature flags:** `buildflags/buildflags.gni`
## Chromium Upgrade Workflow
When working on the `roller/chromium/main` branch to upgrade Chromium activate the "Electron Chromium Upgrade" skill.
## Code Style
**C++:** Follows Chromium style, enforced by clang-format
**TypeScript/JavaScript:** ESLint configuration in `.eslintrc.json`
**Linting:**
```bash
npm run lint # Run all linters
npm run lint:clang-format # C++ formatting
```
## Key Files
| File | Purpose |
|------|---------|
| `BUILD.gn` | Main GN build configuration |
| `DEPS` | Dependency versions and checkout paths |
| `patches/config.json` | Patch target configuration |
| `filenames.gni` | Source file lists by platform |
| `package.json` | Node.js dependencies and scripts |
## Environment Variables
| Variable | Purpose |
|----------|---------|
| `GN_EXTRA_ARGS` | Additional GN arguments (useful in CI) |
| `ELECTRON_RUN_AS_NODE=1` | Run Electron as Node.js |
## Useful Git Commands for Chromium
```bash
# Find CL that changed a file
cd ..
git log --oneline -10 -- {file}
git blame -L {start},{end} -- {file}
# Look for Chromium CL reference in commit
git log -1 {commit_sha} # Find "Reviewed-on:" line
# Find which patch affects a file
grep -l "filename.cc" patches/chromium/*.patch
```
## CI/CD
GitHub Actions workflows in `.github/workflows/`:
- `build.yml` - Main build workflow
- `pipeline-electron-lint.yml` - Linting
- `pipeline-segment-electron-test.yml` - Testing
## Common Issues
**Patch conflict during sync:**
- Use `e sync --3` for 3-way merge
- Check if file was renamed/moved upstream
- Verify patch is still needed
**Build error in patched file:**
- Find the patch: `grep -l "filename" patches/chromium/*.patch`
- Match existing patch style (#if 0 guards, BUILDFLAG conditionals, etc.)
**Remote build issues:**
- Try `e build --no-remote` to build locally
- Check reclient/siso configuration in your build config

2
script/lint.js
View File

@@ -281,7 +281,7 @@ const LINTERS = [{
}, {
key: 'md',
roots: ['.'],
ignoreRoots: ['.git', '.github/workflows/node_modules', 'node_modules', 'spec/node_modules', 'spec/fixtures/native-addon'],
ignoreRoots: ['.claude', '.git', '.github/workflows/node_modules', 'node_modules', 'spec/node_modules', 'spec/fixtures/native-addon'],
test: filename => filename.endsWith('.md'),
run: async (opts, filenames) => {
const { getCodeBlocks } = await import('@electron/lint-roller/dist/lib/markdown.js');